@hasna/conversations 0.2.1 → 0.2.3

package/bin/index.js

@@ -6,39 +6,60 @@ var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
-var __moduleCache = /* @__PURE__ */ new WeakMap;
 var __toCommonJS = (from) => {
-  var entry = __moduleCache.get(from), desc;
+  var entry = (__moduleCache ??= new WeakMap).get(from), desc;
   if (entry)
     return entry;
   entry = __defProp({}, "__esModule", { value: true });
-  if (from && typeof from === "object" || typeof from === "function")
-    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
-      get: () => from[key],
-      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-    }));
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (var key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(entry, key))
+        __defProp(entry, key, {
+          get: __accessProp.bind(from, key),
+          enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+        });
+  }
   __moduleCache.set(from, entry);
   return entry;
 };
+var __moduleCache;
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
@@ -2382,12 +2403,64 @@ function getMessageById(id) {
   const row = db2.prepare("SELECT * FROM messages WHERE id = ?").get(id);
   return row ? parseMessage(row) : null;
 }
+function markReadByIds(ids) {
+  const db2 = getDb();
+  if (ids.length === 0)
+    return 0;
+  const placeholders = ids.map(() => "?").join(", ");
+  const stmt = db2.prepare(`UPDATE messages SET read_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE id IN (${placeholders}) AND read_at IS NULL`);
+  const result = stmt.run(...ids);
+  return result.changes;
+}
 function markAllRead(agent) {
   const db2 = getDb();
   const stmt = db2.prepare(`UPDATE messages SET read_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE to_agent = ? AND read_at IS NULL`);
   const result = stmt.run(agent);
   return result.changes;
 }
+function readDigest(opts = {}) {
+  const db2 = getDb();
+  const countConditions = ["read_at IS NULL"];
+  const countParams = [];
+  if (opts.space) {
+    countConditions.push("space = ?");
+    countParams.push(opts.space);
+  }
+  if (opts.session_id) {
+    countConditions.push("session_id = ?");
+    countParams.push(opts.session_id);
+  }
+  if (opts.to) {
+    countConditions.push("to_agent = ?");
+    countParams.push(opts.to);
+  }
+  if (opts.since) {
+    countConditions.push("created_at > ?");
+    countParams.push(opts.since);
+  }
+  if (opts.project_id) {
+    countConditions.push("project_id = ?");
+    countParams.push(opts.project_id);
+  }
+  const countWhere = `WHERE ${countConditions.join(" AND ")}`;
+  const totalUnread = db2.prepare(`SELECT COUNT(*) as n FROM messages ${countWhere}`).get(...countParams).n;
+  const messages = readMessages({ ...opts, unread_only: opts.unread_only ?? true });
+  if (messages.length > 0) {
+    markReadByIds(messages.map((m) => m.id));
+  }
+  const digest = messages.map((m) => ({
+    id: m.id,
+    from: m.from_agent,
+    created_at: m.created_at,
+    preview: m.content.slice(0, 100) + (m.content.length > 100 ? "\u2026" : ""),
+    priority: m.priority,
+    has_attachments: Array.isArray(m.attachments) && m.attachments.length > 0,
+    space: m.space,
+    to: m.to_agent,
+    unread: !m.read_at
+  }));
+  return { messages: digest, total_unread: totalUnread, shown: digest.length };
+}
 function escapeCsvField(value) {
   if (value === null || value === undefined)
     return "";
@@ -2571,6 +2644,39 @@ function searchMessages(opts) {
     return { ...msg, snippet: null, relevance_score: 0 };
   });
 }
+function listUnreadCounts(agent) {
+  const db2 = getDb();
+  if (agent) {
+    const rows2 = db2.prepare(`
+      SELECT
+        space,
+        COUNT(CASE WHEN read_at IS NULL AND (to_agent = ? OR to_agent IS NULL OR to_agent = '') THEN 1 END) AS unread_count,
+        MAX(created_at) AS latest_message_at
+      FROM messages
+      WHERE space IN (
+        SELECT DISTINCT space FROM space_members WHERE agent = ?
+        UNION
+        SELECT DISTINCT space FROM messages WHERE to_agent = ? AND space IS NOT NULL
+      )
+      GROUP BY space
+      HAVING COUNT(*) > 0
+      ORDER BY unread_count DESC, latest_message_at DESC
+    `).all(agent, agent, agent);
+    return rows2;
+  }
+  const rows = db2.prepare(`
+    SELECT
+      space,
+      COUNT(CASE WHEN read_at IS NULL THEN 1 END) AS unread_count,
+      MAX(created_at) AS latest_message_at
+    FROM messages
+    WHERE space IS NOT NULL
+    GROUP BY space
+    HAVING COUNT(*) > 0
+    ORDER BY unread_count DESC, latest_message_at DESC
+  `).all();
+  return rows;
+}
 var init_messages = __esm(() => {
   init_db();
   init_webhooks();
@@ -3431,6 +3537,9 @@ function isActiveSession(lastSeenAt) {
   const nowMs = Date.now();
   return nowMs - lastSeenMs < CONFLICT_THRESHOLD_SECONDS * 1000;
 }
+function isAgentConflict(result) {
+  return result.conflict === true;
+}
 function registerAgent(name, sessionId, role, projectId) {
   const db2 = getDb();
   const normalizedName = name.trim().toLowerCase();
@@ -4207,7 +4316,7 @@ var init_poll = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/conversations",
-    version: "0.2.1",
+    version: "0.2.3",
     description: "Real-time CLI messaging for AI agents",
     type: "module",
     bin: {
@@ -33216,6 +33325,7 @@ function acquireLock(resourceType, resourceId, agentId, lockType = "advisory", e
   const db2 = getDb();
   return db2.transaction(() => {
     cleanExpiredLocks();
+    releaseStaleAgentLocks();
     const existing = db2.prepare(`
       SELECT * FROM resource_locks
       WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
@@ -33242,6 +33352,55 @@ function acquireLock(resourceType, resourceId, agentId, lockType = "advisory", e
     return { acquired: true, lock };
   }).immediate();
 }
+function bulkAcquireLock(resources, agentId) {
+  const db2 = getDb();
+  return db2.transaction(() => {
+    cleanExpiredLocks();
+    releaseStaleAgentLocks();
+    const acquired = [];
+    for (const { resource_type, resource_id, lock_type = "advisory", expiry_ms = DEFAULT_LOCK_EXPIRY_MS } of resources) {
+      const existing = db2.prepare(`
+        SELECT * FROM resource_locks
+        WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+      `).get(resource_type, resource_id, lock_type);
+      if (existing && existing.agent_id !== agentId) {
+        throw { _bulkConflict: true, resource_type, resource_id, held_by: existing.agent_id };
+      }
+      const expiresAt = new Date(Date.now() + expiry_ms).toISOString().slice(0, -1);
+      if (existing) {
+        db2.prepare(`
+          UPDATE resource_locks SET expires_at = ?, locked_at = strftime('%Y-%m-%dT%H:%M:%f', 'now')
+          WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+        `).run(expiresAt, resource_type, resource_id, lock_type);
+      } else {
+        db2.prepare(`
+          INSERT INTO resource_locks (resource_type, resource_id, agent_id, lock_type, locked_at, expires_at)
+          VALUES (?, ?, ?, ?, strftime('%Y-%m-%dT%H:%M:%f', 'now'), ?)
+        `).run(resource_type, resource_id, agentId, lock_type, expiresAt);
+      }
+      const lock = db2.prepare(`
+        SELECT * FROM resource_locks WHERE resource_type = ? AND resource_id = ? AND lock_type = ?
+      `).get(resource_type, resource_id, lock_type);
+      acquired.push(lock);
+    }
+    return { acquired: true, locks: acquired };
+  }).immediate();
+}
+function tryBulkAcquireLock(resources, agentId) {
+  try {
+    return bulkAcquireLock(resources, agentId);
+  } catch (err) {
+    const e = err;
+    if (e?._bulkConflict) {
+      return {
+        acquired: false,
+        locks: [],
+        blocked_by: { resource_type: e.resource_type, resource_id: e.resource_id, held_by: e.held_by }
+      };
+    }
+    throw err;
+  }
+}
 function releaseLock(resourceType, resourceId, agentId) {
   const db2 = getDb();
   const result = db2.prepare(`
@@ -33253,6 +33412,7 @@ function releaseLock(resourceType, resourceId, agentId) {
 function checkLock(resourceType, resourceId) {
   const db2 = getDb();
   cleanExpiredLocks();
+  releaseStaleAgentLocks();
   return db2.prepare(`
     SELECT * FROM resource_locks
     WHERE resource_type = ? AND resource_id = ?
@@ -33260,6 +33420,17 @@ function checkLock(resourceType, resourceId) {
     LIMIT 1
   `).get(resourceType, resourceId);
 }
+function releaseStaleAgentLocks() {
+  const db2 = getDb();
+  const result = db2.prepare(`
+    DELETE FROM resource_locks
+    WHERE LOWER(agent_id) IN (
+      SELECT LOWER(agent) FROM agent_presence
+      WHERE last_seen_at < strftime('%Y-%m-%dT%H:%M:%f', 'now', '-${STALE_HEARTBEAT_SECONDS} seconds')
+    )
+  `).run();
+  return result.changes;
+}
 function cleanExpiredLocks() {
   const db2 = getDb();
   const result = db2.prepare(`
@@ -33270,6 +33441,7 @@ function cleanExpiredLocks() {
 function listLocks(opts) {
   const db2 = getDb();
   cleanExpiredLocks();
+  releaseStaleAgentLocks();
   let query = "SELECT * FROM resource_locks WHERE 1=1";
   const params = [];
   if (opts?.resource_type) {
@@ -33283,10 +33455,36 @@ function listLocks(opts) {
   query += " ORDER BY locked_at ASC";
   return db2.prepare(query).all(...params);
 }
-var DEFAULT_LOCK_EXPIRY_MS;
+function listLocksEnriched(opts) {
+  const locks = listLocks(opts);
+  const db2 = getDb();
+  const nowMs = Date.now();
+  return locks.map((lock) => {
+    const lockedMs = new Date(lock.locked_at + "Z").getTime();
+    const expiresMs = new Date(lock.expires_at + "Z").getTime();
+    const presenceRow = db2.prepare(`
+      SELECT role, status, last_seen_at, project_id FROM agent_presence WHERE LOWER(agent) = LOWER(?)
+    `).get(lock.agent_id);
+    const agent = presenceRow ? {
+      role: presenceRow.role ?? null,
+      status: presenceRow.status ?? null,
+      online: presenceRow.last_seen_at ? nowMs - new Date(presenceRow.last_seen_at + "Z").getTime() < 60000 : false,
+      last_seen_at: presenceRow.last_seen_at ?? null,
+      project_id: presenceRow.project_id ?? null
+    } : null;
+    return {
+      ...lock,
+      locked_seconds_ago: Math.round((nowMs - lockedMs) / 1000),
+      expires_in_seconds: Math.round((expiresMs - nowMs) / 1000),
+      agent
+    };
+  });
+}
+var DEFAULT_LOCK_EXPIRY_MS, STALE_HEARTBEAT_SECONDS;
 var init_locks = __esm(() => {
   init_db();
   DEFAULT_LOCK_EXPIRY_MS = 5 * 60 * 1000;
+  STALE_HEARTBEAT_SECONDS = 30 * 60;
 });
 
 // src/mcp/index.ts
@@ -33369,7 +33567,8 @@ var init_mcp2 = __esm(() => {
       project_id: exports_external.string().optional(),
       since: exports_external.string().optional(),
       limit: exports_external.coerce.number().optional(),
-      unread_only: exports_external.coerce.boolean().optional()
+      unread_only: exports_external.coerce.boolean().optional(),
+      mark_read: exports_external.coerce.boolean().optional()
     }
   }, async (args) => {
     const agent = resolveIdentity(args.from);
@@ -33377,6 +33576,9 @@ var init_mcp2 = __esm(() => {
       ...args,
       project_id: args.project_id ?? resolveProjectId(undefined, agent)
     });
+    if (args.mark_read !== false && messages.length > 0) {
+      markReadByIds(messages.map((m) => m.id));
+    }
     return {
       content: [{ type: "text", text: JSON.stringify(messages) }]
     };
@@ -33535,6 +33737,17 @@ var init_mcp2 = __esm(() => {
       content: [{ type: "text", text: JSON.stringify(spaces) }]
     };
   });
+  server.registerTool("list_unread_counts", {
+    description: "Get unread message counts per space without fetching message content. Use this at session start to triage which spaces need attention before calling read_messages.",
+    inputSchema: {
+      agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts.")
+    }
+  }, async (args) => {
+    const counts = listUnreadCounts(args.agent);
+    return {
+      content: [{ type: "text", text: JSON.stringify(counts) }]
+    };
+  });
   server.registerTool("send_to_space", {
     description: "Post a message to a space.",
     inputSchema: {
@@ -33572,15 +33785,36 @@ var init_mcp2 = __esm(() => {
     inputSchema: {
       space: exports_external.string(),
       since: exports_external.string().optional(),
-      limit: exports_external.coerce.number().optional()
+      limit: exports_external.coerce.number().optional(),
+      mark_read: exports_external.coerce.boolean().optional()
     }
   }, async (args) => {
-    const { space, since, limit } = args;
+    const { space, since, limit, mark_read } = args;
     const messages = readMessages({ space, since, limit });
+    if (mark_read !== false && messages.length > 0) {
+      markReadByIds(messages.map((m) => m.id));
+    }
     return {
       content: [{ type: "text", text: JSON.stringify(messages) }]
     };
   });
+  server.registerTool("read_digest", {
+    description: "Lightweight unread message digest \u2014 returns preview-only summaries, auto-marks as read. Use instead of read_messages on busy spaces to avoid token overflow.",
+    inputSchema: {
+      space: exports_external.string().optional(),
+      session_id: exports_external.string().optional(),
+      to: exports_external.string().optional(),
+      since: exports_external.string().optional(),
+      limit: exports_external.coerce.number().optional(),
+      project_id: exports_external.string().optional()
+    }
+  }, async (args) => {
+    const { space, session_id, to, since, limit, project_id } = args;
+    const result = readDigest({ space, session_id, to, since, limit, project_id });
+    return {
+      content: [{ type: "text", text: JSON.stringify(result) }]
+    };
+  });
   server.registerTool("join_space", {
     description: "Join a space as a member.",
     inputSchema: {
@@ -34113,18 +34347,29 @@ var init_mcp2 = __esm(() => {
     return { content: [{ type: "text", text: JSON.stringify(summary) }] };
   });
   server.registerTool("acquire_lock", {
-    description: "Acquire an advisory or exclusive lock on a resource. Returns conflict info if another agent holds the lock.",
+    description: "Acquire an advisory or exclusive lock on a resource. Returns conflict info if another agent holds the lock. On conflict, auto-DMs the holding agent.",
     inputSchema: {
       resource_type: exports_external.string(),
       resource_id: exports_external.string(),
       lock_type: exports_external.enum(["advisory", "exclusive"]).optional(),
       expiry_ms: exports_external.coerce.number().optional(),
-      from: exports_external.string().optional()
+      from: exports_external.string().optional(),
+      auto_dm: exports_external.coerce.boolean().optional()
     }
   }, async (args) => {
-    const { resource_type, resource_id, lock_type, expiry_ms, from: fromParam } = args;
+    const { resource_type, resource_id, lock_type, expiry_ms, from: fromParam, auto_dm } = args;
     const agent = resolveIdentity(fromParam);
     const result = acquireLock(resource_type, resource_id, agent, lock_type ?? "advisory", expiry_ms);
+    if (!result.acquired && result.held_by && auto_dm !== false) {
+      try {
+        sendMessage({
+          from: agent,
+          to: result.held_by,
+          content: `Lock conflict: I (@${agent}) tried to acquire ${lock_type ?? "advisory"} lock on \`${resource_type}/${resource_id}\` but you hold it. If you no longer need it, release it with \`release_lock\`.`,
+          priority: "high"
+        });
+      } catch {}
+    }
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
   });
   server.registerTool("release_lock", {
@@ -34151,15 +34396,50 @@ var init_mcp2 = __esm(() => {
     return { content: [{ type: "text", text: JSON.stringify(lock ?? { locked: false }) }] };
   });
   server.registerTool("list_locks", {
-    description: "List all active (non-expired) locks. Filter by resource_type or agent.",
+    description: "List all active (non-expired) locks enriched with agent presence details (status, online, last_seen_at) and time context (locked_seconds_ago, expires_in_seconds). Filter by resource_type or agent.",
     inputSchema: {
       resource_type: exports_external.string().optional(),
       agent_id: exports_external.string().optional()
     }
   }, async (args) => {
-    const locks = listLocks({ resource_type: args.resource_type, agent_id: args.agent_id });
+    const locks = listLocksEnriched({ resource_type: args.resource_type, agent_id: args.agent_id });
     return { content: [{ type: "text", text: JSON.stringify(locks) }] };
   });
+  server.registerTool("bulk_acquire_lock", {
+    description: "Atomically acquire multiple locks at once. All-or-nothing: if any lock is held by another agent, none are acquired. Returns blocked_by info on conflict.",
+    inputSchema: {
+      resources: exports_external.array(exports_external.object({
+        resource_type: exports_external.string(),
+        resource_id: exports_external.string(),
+        lock_type: exports_external.enum(["advisory", "exclusive"]).optional(),
+        expiry_ms: exports_external.coerce.number().optional()
+      })),
+      from: exports_external.string().optional(),
+      auto_dm: exports_external.coerce.boolean().optional()
+    }
+  }, async (args) => {
+    const agent = resolveIdentity(args.from);
+    const result = tryBulkAcquireLock(args.resources, agent);
+    if (!result.acquired && result.blocked_by && args.auto_dm !== false) {
+      try {
+        sendMessage({
+          from: agent,
+          to: result.blocked_by.held_by,
+          content: `Bulk lock conflict: I (@${agent}) tried to atomically acquire ${args.resources.length} locks but you hold \`${result.blocked_by.resource_type}/${result.blocked_by.resource_id}\`. Release it when done.`,
+          priority: "high"
+        });
+      } catch {}
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
+  });
+  server.registerTool("clean_expired_locks", {
+    description: "Clean up expired locks and auto-release locks held by agents whose heartbeat has been stale for >30 minutes. Returns counts of removed locks.",
+    inputSchema: {}
+  }, async () => {
+    const stale = releaseStaleAgentLocks();
+    const expired = cleanExpiredLocks();
+    return { content: [{ type: "text", text: JSON.stringify({ released_stale_agent: stale, released_expired: expired, total: stale + expired }) }] };
+  });
   server.registerTool("get_thread_replies", {
     description: "Get all replies in a thread for a given parent message ID.",
     inputSchema: {
@@ -34343,6 +34623,7 @@ var init_mcp2 = __esm(() => {
     const all = [
       "send_message",
       "read_messages",
+      "read_digest",
       "list_sessions",
       "reply",
       "mark_read",
@@ -34381,9 +34662,11 @@ var init_mcp2 = __esm(() => {
       "get_reactions",
       "get_reaction_summary",
       "acquire_lock",
+      "bulk_acquire_lock",
       "release_lock",
       "check_lock",
       "list_locks",
+      "clean_expired_locks",
       "get_thread_replies",
       "set_focus",
       "get_focus",
@@ -34409,16 +34692,18 @@ var init_mcp2 = __esm(() => {
   }, async ({ names }) => {
     const descriptions = {
       send_message: "Send DM to agent. Required: to, content. Optional: from?, priority?(low|normal|high|urgent), blocking?",
-      read_messages: "Read messages with filters. Optional: session_id?, from?, to?, space?, since?(ISO), limit?, unread_only?",
+      read_messages: "Read messages with filters. Optional: session_id?, from?, to?, space?, since?(ISO), limit?, unread_only?, mark_read?(default true \u2014 auto-marks returned messages as read, pass false to peek without consuming)",
+      read_digest: "Lightweight unread digest \u2014 preview only (no full bodies), auto-marks read, never overflows tokens. Returns { messages, total_unread, shown }. Optional: space?, session_id?, to?, since?(ISO), limit?, project_id?",
       list_sessions: "List all DM sessions. Optional: agent?(filter by participant)",
       reply: "Reply to a message in same session. Required: message_id, content. Optional: from?",
       mark_read: "Mark messages as read. Optional: from?, ids?(array), all?(bool \u2014 mark all unread)",
       search_messages: "Full-text search messages. Required: query. Optional: space?, from?, to?, limit?",
       export_messages: "Export messages as JSON or CSV. Optional: space?, session_id?, from?, since?, until?, format?(json|csv)",
       create_space: "Create space and auto-join. Required: name. Optional: from?, description?, parent_id?(max 3 levels), project_id?",
+      list_unread_counts: "Get unread message counts per space (no content). Ideal for session start triage. Optional: agent?(filter to agent's spaces)",
       list_spaces: "List spaces with member/message counts. Optional: project_id?, parent_id?(use 'null' for top-level), include_archived?",
       send_to_space: "Post message to space. Required: space, content. Optional: from?, priority?(low|normal|high|urgent), blocking?",
-      read_space: "Read messages in a space. Required: space. Optional: since?(ISO), limit?",
+      read_space: "Read messages in a space. Required: space. Optional: since?(ISO), limit?, mark_read?(default true \u2014 auto-marks returned messages as read)",
       join_space: "Join a space. Required: space. Optional: from?",
       leave_space: "Leave a space. Required: space. Optional: from?",
       update_space: "Update space fields. Required: name. Optional: description?, parent_id?(use 'null' to remove), project_id?(use 'null' to remove)",
@@ -34447,10 +34732,12 @@ var init_mcp2 = __esm(() => {
       remove_reaction: "Remove emoji reaction from a message. Required: message_id, emoji. Optional: from?",
       get_reactions: "Get all reactions for a message. Required: message_id",
       get_reaction_summary: "Get emoji counts + agent lists for a message. Required: message_id",
-      acquire_lock: "Acquire advisory/exclusive lock on a resource. Required: resource_type, resource_id. Optional: lock_type?(advisory|exclusive), expiry_ms?, from?",
+      acquire_lock: "Acquire advisory/exclusive lock on a resource. On conflict, auto-DMs the holding agent. Required: resource_type, resource_id. Optional: lock_type?(advisory|exclusive), expiry_ms?, from?, auto_dm?(default true)",
+      bulk_acquire_lock: "Atomically acquire multiple locks (all-or-nothing). Required: resources[]{resource_type,resource_id,lock_type?,expiry_ms?}. Optional: from?, auto_dm?(default true). Returns blocked_by on conflict.",
       release_lock: "Release lock held by agent. Required: resource_type, resource_id. Optional: from?",
       check_lock: "Check if resource is locked and who holds it. Required: resource_type, resource_id",
-      list_locks: "List active locks. Optional: resource_type?, agent_id?",
+      list_locks: "List active locks enriched with agent presence + time context. Optional: resource_type?, agent_id?",
+      clean_expired_locks: "Release expired locks + locks held by agents with stale heartbeat (>30 min). Returns {released_stale_agent, released_expired, total}",
       get_thread_replies: "Get all replies in a thread. Required: message_id. Optional: limit?",
       set_focus: "Set agent focus to a project. All read tools default to this scope. Required: project_id. Optional: from?",
       get_focus: "Get current focus: session focus, DB project_id, effective project_id. Optional: from?",
@@ -36099,6 +36386,33 @@ program2.command("read").description("Read messages").option("--session <id>", "
   }
   closeDb();
 });
+program2.command("digest").description("Show unread message digest (preview only, auto-marks read)").argument("[space]", "Space name to digest (omit for DMs)").option("--since <timestamp>", "Messages after this ISO timestamp").option("--limit <n>", "Max messages to show", parseInt).option("--to <agent>", "Filter by recipient (for DMs)").option("--json", "Output as JSON").action((spaceArg, opts) => {
+  const result = readDigest({
+    space: spaceArg || undefined,
+    since: opts.since,
+    limit: opts.limit,
+    to: opts.to
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(chalk3.bold(`Unread: ${result.total_unread} total, showing ${result.shown}`));
+    if (result.messages.length === 0) {
+      console.log(chalk3.dim("  No unread messages."));
+    } else {
+      for (const msg of result.messages) {
+        const time3 = chalk3.dim(msg.created_at.slice(11, 19));
+        const from = chalk3.cyan(msg.from);
+        const dest = msg.space ? chalk3.magenta(`#${msg.space}`) : chalk3.yellow(msg.to ?? "?");
+        const priority = msg.priority !== "normal" ? chalk3.red(` [${msg.priority}]`) : "";
+        const att = msg.has_attachments ? chalk3.dim(" \uD83D\uDCCE") : "";
+        console.log(`${time3} ${from} \u2192 ${dest}${priority}${att}`);
+        console.log(`  ${chalk3.dim(msg.preview)}`);
+      }
+    }
+  }
+  closeDb();
+});
 program2.command("search").description("Search messages by content").argument("<query>", "Search query string").option("--space <name>", "Filter by space").option("--from <agent>", "Filter by sender").option("--to <agent>", "Filter by recipient").option("--limit <n>", "Max results to return", parseInt).option("--json", "Output as JSON").action((query, opts) => {
   const q = typeof query === "string" ? query.trim() : "";
   if (!q) {
@@ -37184,6 +37498,85 @@ agents.command("rename").description("Rename an agent in the presence list").arg
   }
   closeDb();
 });
+agents.command("register").description("Register an agent with conflict detection (30 min active window)").argument("<name>", "Agent name to register").option("--session <id>", "Session ID (default: random UUID)").option("--role <role>", "Agent role (default: agent)").option("--project <id>", "Project ID to lock agent to").option("--force", "Force takeover even if another session is active").option("--json", "Output as JSON").action((name, opts) => {
+  const agentName = (typeof name === "string" ? name : "").trim();
+  if (!agentName) {
+    console.error(chalk3.red("Agent name is required."));
+    process.exit(1);
+  }
+  const sessionId = opts.session || crypto.randomUUID();
+  const result = registerAgent(agentName, sessionId, opts.role, opts.project);
+  if (isAgentConflict(result)) {
+    if (opts.json) {
+      console.log(JSON.stringify(result));
+    } else {
+      console.error(chalk3.red(`Conflict: agent "${agentName}" is already active (last seen: ${result.last_seen_at}).`));
+      console.error(chalk3.dim("Use --force or wait 30 minutes for the session to expire."));
+    }
+    process.exit(1);
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(result));
+  } else {
+    const action = result.took_over ? chalk3.yellow("took over") : result.created ? chalk3.green("registered") : chalk3.cyan("updated");
+    console.log(`  ${action}  ${chalk3.bold(result.agent.agent)}  session: ${chalk3.dim(sessionId)}`);
+  }
+  closeDb();
+});
+agents.command("heartbeat").description("Send a presence heartbeat to mark yourself as active").option("--from <agent>", "Agent identity (default: CONVERSATIONS_AGENT_ID or auto)").option("--status <status>", "Status: online, busy, idle (default: online)").option("--json", "Output as JSON").action((opts) => {
+  const agent = resolveIdentity(opts.from);
+  const status = opts.status || "online";
+  heartbeat(agent, status);
+  if (opts.json) {
+    console.log(JSON.stringify({ agent, status, heartbeat: true }));
+  } else {
+    console.log(`  ${chalk3.green("\u2665")}  ${chalk3.cyan(agent)}  ${chalk3.dim(status)}`);
+  }
+  closeDb();
+});
+var focus = program2.command("focus").description("Manage agent project focus");
+focus.command("set").description("Set your project focus \u2014 scopes read operations to this project").argument("<project>", "Project ID or name").option("--from <agent>", "Agent identity").option("--json", "Output as JSON").action((projectArg, opts) => {
+  const agent = resolveIdentity(opts.from);
+  const project2 = getProject(projectArg) || getProjectByName(projectArg);
+  if (!project2) {
+    console.error(chalk3.red(`Project "${projectArg}" not found.`));
+    process.exit(1);
+  }
+  getDb().prepare("UPDATE agent_presence SET project_id = ? WHERE agent = ?").run(project2.id, agent);
+  if (opts.json) {
+    console.log(JSON.stringify({ agent, project_id: project2.id, project_name: project2.name, focused: true }));
+  } else {
+    console.log(`  ${chalk3.green("focused")}  ${chalk3.cyan(agent)}  \u2192  ${chalk3.bold(project2.name)}  ${chalk3.dim(`(${project2.id})`)}`);
+  }
+  closeDb();
+});
+focus.command("clear").description("Clear your project focus").option("--from <agent>", "Agent identity").option("--json", "Output as JSON").action((opts) => {
+  const agent = resolveIdentity(opts.from);
+  getDb().prepare("UPDATE agent_presence SET project_id = NULL WHERE agent = ?").run(agent);
+  if (opts.json) {
+    console.log(JSON.stringify({ agent, project_id: null, focused: false }));
+  } else {
+    console.log(`  ${chalk3.yellow("unfocused")}  ${chalk3.cyan(agent)}`);
+  }
+  closeDb();
+});
+focus.command("get").description("Show current project focus").option("--from <agent>", "Agent identity").option("--json", "Output as JSON").action((opts) => {
+  const agent = resolveIdentity(opts.from);
+  const presence = getPresence(agent);
+  const projectId = presence?.project_id ?? null;
+  const project2 = projectId ? getProject(projectId) || null : null;
+  if (opts.json) {
+    console.log(JSON.stringify({ agent, project_id: projectId, project_name: project2?.name ?? null }));
+  } else {
+    if (projectId) {
+      const name = project2?.name ?? chalk3.dim("(unknown)");
+      console.log(`  ${chalk3.cyan(agent)}  focused on  ${chalk3.bold(name)}  ${chalk3.dim(`(${projectId})`)}`);
+    } else {
+      console.log(`  ${chalk3.cyan(agent)}  ${chalk3.dim("no focus set")}`);
+    }
+  }
+  closeDb();
+});
 program2.command("whoami").description("Show current agent identity and online status").option("--from <agent>", "Explicit agent identity").action((opts) => {
   const envValue = process.env.CONVERSATIONS_AGENT_ID?.trim();
   const agent = resolveIdentity(opts.from);