@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/team/team-db-feed.js

@@ -44,41 +44,53 @@ export const postFeedEvent = (db, eventData = {}) => {
   return { ...row, metadata: JSON.parse(row.metadata || '{}') };
 };
 
+// Rows whose metadata carries $.archived = 1 stay in the table (cleanup archives, never deletes)
+// but drop out of feed, status and mailbox listings.
+export const NOT_ARCHIVED_SQL = "COALESCE(json_extract(CASE WHEN json_valid(metadata) THEN metadata END, '$.archived'), 0) != 1";
+
+const parseRow = (r) => ({ ...r, metadata: JSON.parse(r.metadata || '{}') });
+
+// With since_id the feed reads forward in id order (a cursor). Without it, it returns the newest
+// `limit` rows, still in chronological order, so status cards show recent activity, not the oldest rows.
 export const queryFeed = (db, filter = {}) => {
   if (!db) return [];
   let query = 'SELECT * FROM agent_feed';
-  const conditions = [];
+  const conditions = [NOT_ARCHIVED_SQL];
   const params = [];
+  const hasCursor = Boolean(filter.since_id);
 
-  if (filter.since_id) {
+  if (hasCursor) {
     conditions.push('id > ?');
     params.push(Number(filter.since_id));
   }
-  if (filter.thread_id) {
+  const hasThread = Boolean(filter.thread_id);
+  if (hasThread) {
     conditions.push('(thread_id = ? OR id = ?)');
     params.push(Number(filter.thread_id), Number(filter.thread_id));
   }
-  if (filter.task_id) {
+  const hasTask = Boolean(filter.task_id);
+  if (hasTask) {
     conditions.push('task_id = ?');
     params.push(Number(filter.task_id));
   }
-  if (filter.event_type) {
+  const hasEventType = Boolean(filter.event_type);
+  if (hasEventType) {
     conditions.push('event_type = ?');
     params.push(filter.event_type);
   }
-  if (filter.agent_id) {
+  const hasAgent = Boolean(filter.agent_id);
+  if (hasAgent) {
     const cleanId = formatHandle(filter.agent_id);
     conditions.push('(recipient_id IS NULL OR recipient_id = ? OR author_id = ?)');
     params.push(cleanId, cleanId);
   }
 
-  const hasConditions = conditions.length > 0;
-  if (hasConditions) query += ` WHERE ${conditions.join(' AND ')}`;
+  query += ` WHERE ${conditions.join(' AND ')}`;
   const limit = Math.min(Number(filter.limit || 50), 200);
-  query += ` ORDER BY id ASC LIMIT ${limit}`;
+  const direction = hasCursor ? 'ASC' : 'DESC';
+  query += ` ORDER BY id ${direction} LIMIT ${limit}`;
 
-  return db.prepare(query).all(...params).map((r) => ({
-    ...r,
-    metadata: JSON.parse(r.metadata || '{}')
-  }));
+  const rows = db.prepare(query).all(...params).map(parseRow);
+  if (hasCursor) return rows;
+  return rows.reverse();
 };

package/cli/team/team-db-lock-promotion.js

@@ -1,33 +1,58 @@
 /**
- * Chemical X Protocol: FIFO Lock Promotion & Expiration Cleanup
+ * Chemical X Protocol: FIFO Lock Promotion, Waiter Hygiene & Expiration Cleanup
+ * Every write here only changes the exact row it judged, so a concurrent acquire is never clobbered.
  */
 
 import { postFeedEvent } from './team-db-feed.js';
 import { isPidAlive } from './team-db-transaction.js';
 
 export const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+export const WAITER_TTL_MS = 2 * DEFAULT_TTL_MS;
 
-export const promoteNextWaiter = (db, filePath, pid = 0) => {
-  const hasDb = Boolean(db);
-  const hasPath = Boolean(filePath);
-  const canPromote = hasDb && hasPath;
+const hasTrackedPid = (pid) => typeof pid === 'number' && pid > 0;
+
+export const isOwnerProcessDead = (row) => hasTrackedPid(row?.pid) && !isPidAlive(row.pid);
+
+export const describeLease = (lease, now = Date.now()) => {
+  const hasLease = Boolean(lease);
+  if (!hasLease) return null;
+  const expired = lease.expires_at <= now;
+  const holderDead = isOwnerProcessDead(lease);
+  return { ...lease, expired, holderDead, active: !expired && !holderDead };
+};
+
+const lastSeenAt = (waiter) => (waiter.last_seen_at > 0 ? waiter.last_seen_at : waiter.requested_at);
+
+const isWaiterStale = (waiter, now) => lastSeenAt(waiter) <= now - WAITER_TTL_MS || isOwnerProcessDead(waiter);
+
+export const expireStaleWaiters = (db, filePath, now = Date.now()) => {
+  const waiting = db.prepare("SELECT * FROM file_lock_queue WHERE file_path = ? AND status = 'waiting'").all(filePath);
+  const stale = waiting.filter((waiter) => isWaiterStale(waiter, now));
+  const markExpired = db.prepare("UPDATE file_lock_queue SET status = 'expired' WHERE id = ? AND status = 'waiting'");
+  for (const waiter of stale) markExpired.run(waiter.id);
+  return stale;
+};
+
+export const promoteNextWaiter = (db, filePath) => {
+  const canPromote = Boolean(db) && Boolean(filePath);
   if (!canPromote) return null;
 
+  const now = Date.now();
+  expireStaleWaiters(db, filePath, now);
   const waiterQuery = "SELECT * FROM file_lock_queue WHERE file_path = ? AND status = 'waiting' ORDER BY priority ASC, id ASC LIMIT 1";
   const waiter = db.prepare(waiterQuery).get(filePath);
-
   const hasWaiter = Boolean(waiter);
   if (!hasWaiter) return null;
 
-  const now = Date.now();
   const expiresAt = now + DEFAULT_TTL_MS;
-  db.prepare("UPDATE file_lock_queue SET status = 'granted' WHERE id = ?").run(waiter.id);
-
-  const upsertSql = `INSERT INTO file_leases (file_path, locked_by, acquired_at, expires_at, purpose, pid)
-    VALUES (?, ?, ?, ?, ?, ?)
-    ON CONFLICT(file_path) DO UPDATE SET locked_by = excluded.locked_by, acquired_at = excluded.acquired_at, expires_at = excluded.expires_at, purpose = excluded.purpose, pid = excluded.pid`;
-  db.prepare(upsertSql).run(filePath, waiter.agent_id, now, expiresAt, waiter.purpose || 'Promoted from FIFO queue', pid);
+  const insertSql = `INSERT INTO file_leases (file_path, locked_by, acquired_at, expires_at, purpose, pid)
+    VALUES (?, ?, ?, ?, ?, ?) ON CONFLICT(file_path) DO NOTHING`;
+  const purpose = waiter.purpose || 'Promoted from FIFO queue';
+  const inserted = db.prepare(insertSql).run(filePath, waiter.agent_id, now, expiresAt, purpose, waiter.pid || 0);
+  const isGranted = inserted.changes === 1;
+  if (!isGranted) return null; // another agent already holds the file; the waiter keeps its place
 
+  db.prepare("UPDATE file_lock_queue SET status = 'granted' WHERE id = ? AND status = 'waiting'").run(waiter.id);
   postFeedEvent(db, {
     author_id: '@system',
     recipient_id: waiter.agent_id,
@@ -36,66 +61,85 @@ export const promoteNextWaiter = (db, filePath, pid = 0) => {
     message: `File lock granted to ${waiter.agent_id} for ${filePath} from FIFO queue`,
     metadata: { queueId: waiter.id, expiresAt }
   });
-
   return { waiter, expiresAt };
 };
 
-export const enqueueWaiter = (db, filePath, cleanId, existingLease, options = {}, now = Date.now()) => {
-  const priority = Number(options.priority || 2);
-  const purpose = options.purpose || '';
-  const info = db.prepare(`
-    INSERT INTO file_lock_queue (file_path, agent_id, requested_at, status, priority, purpose)
-    VALUES (?, ?, ?, 'waiting', ?, ?)
-  `).run(filePath, cleanId, now, priority, purpose);
-
+const countPosition = (db, filePath, queueId) => {
   const posRow = db.prepare(`
     SELECT COUNT(*) as pos FROM file_lock_queue
     WHERE file_path = ? AND status = 'waiting' AND id <= ?
-  `).get(filePath, info.lastInsertRowid);
-  const position = posRow?.pos || 1;
+  `).get(filePath, queueId);
+  return posRow?.pos || 1;
+};
 
-  postFeedEvent(db, {
-    author_id: cleanId,
-    event_type: 'lock_queued',
-    file_path: filePath,
-    message: `${cleanId} joined FIFO queue at position ${position} for ${filePath}`,
-    metadata: { queueId: info.lastInsertRowid, position, heldBy: existingLease.locked_by }
-  });
+export const enqueueWaiter = (db, filePath, cleanId, existingLease, options = {}, now = Date.now()) => {
+  expireStaleWaiters(db, filePath, now);
+  const pid = hasTrackedPid(options.pid) ? options.pid : 0;
+  const findSql = "SELECT * FROM file_lock_queue WHERE file_path = ? AND agent_id = ? AND status = 'waiting' ORDER BY id ASC LIMIT 1";
+  const existingEntry = db.prepare(findSql).get(filePath, cleanId);
+  const isRepoll = Boolean(existingEntry);
+
+  let queueId = existingEntry?.id;
+  if (isRepoll) {
+    db.prepare('UPDATE file_lock_queue SET last_seen_at = ?, pid = CASE WHEN ? > 0 THEN ? ELSE pid END WHERE id = ?')
+      .run(now, pid, pid, queueId);
+  } else {
+    const info = db.prepare(`
+      INSERT INTO file_lock_queue (file_path, agent_id, requested_at, status, priority, purpose, pid, last_seen_at)
+      VALUES (?, ?, ?, 'waiting', ?, ?, ?, ?)
+    `).run(filePath, cleanId, now, Number(options.priority || 2), options.purpose || '', pid, now);
+    queueId = Number(info.lastInsertRowid);
+  }
+
+  const position = countPosition(db, filePath, queueId);
+  if (!isRepoll) {
+    postFeedEvent(db, {
+      author_id: cleanId,
+      event_type: 'lock_queued',
+      file_path: filePath,
+      message: `${cleanId} joined FIFO queue at position ${position} for ${filePath}`,
+      metadata: { queueId, position, heldBy: existingLease.locked_by }
+    });
+  }
 
   return {
     granted: false,
     queued: true,
-    queueId: info.lastInsertRowid,
+    requeued: isRepoll,
+    queueId,
     position,
     currentHolder: existingLease.locked_by,
     expiresAt: existingLease.expires_at
   };
 };
 
-export const cleanExpiredLeases = (db) => {
+export const cleanExpiredLeases = (db, now = Date.now()) => {
   const hasDb = Boolean(db);
   if (!hasDb) return [];
 
-  const now = Date.now();
   try {
-    const leases = db.prepare('SELECT * FROM file_leases').all();
+    const candidates = db.prepare('SELECT * FROM file_leases WHERE expires_at <= ? OR pid > 0').all(now);
+    const removeExactLease = db.prepare(
+      'DELETE FROM file_leases WHERE file_path = ? AND locked_by = ? AND acquired_at = ? AND expires_at = ?'
+    );
     const cleaned = [];
-    for (const lease of leases) {
-      const isExpired = lease.expires_at <= now;
-      const isDeadProcess = typeof lease.pid === 'number' && lease.pid > 0 && !isPidAlive(lease.pid);
-      const shouldClean = isExpired || isDeadProcess;
-      if (shouldClean) {
-        db.prepare('DELETE FROM file_leases WHERE file_path = ?').run(lease.file_path);
-        const reason = isDeadProcess ? `Process #${lease.pid} terminated` : 'TTL expired';
-        postFeedEvent(db, {
-          author_id: '@system',
-          event_type: 'lock_expired',
-          file_path: lease.file_path,
-          message: `Lease expired for ${lease.file_path} held by ${lease.locked_by} (${reason})`
-        });
-        promoteNextWaiter(db, lease.file_path);
-        cleaned.push(lease);
-      }
+    for (const lease of candidates) {
+      const state = describeLease(lease, now);
+      const isActive = Boolean(state.active);
+      if (isActive) continue;
+      const removal = removeExactLease.run(lease.file_path, lease.locked_by, lease.acquired_at, lease.expires_at);
+      const isRemovedHere = removal.changes === 1;
+      if (!isRemovedHere) continue; // a concurrent writer replaced this lease; it is not ours to delete
+      const reason = state.holderDead ? `Process #${lease.pid} terminated` : 'TTL expired';
+      postFeedEvent(db, {
+        author_id: '@system',
+        event_type: 'lock_expired',
+        file_path: lease.file_path,
+        message: `Lease expired for ${lease.file_path} held by ${lease.locked_by} (${reason})`,
+        metadata: { holder: lease.locked_by, expires_at: lease.expires_at, acquired_at: lease.acquired_at, purpose: lease.purpose || '', reason }
+      });
+      promoteNextWaiter(db, lease.file_path);
+      cleaned.push(lease);
     }
     return cleaned;
   } catch (err) {

package/cli/team/team-db-locks.js

@@ -3,29 +3,65 @@
  * Prevents race collisions with deterministic queueing and reactive promotion
  */
 
+import fs from 'node:fs';
 import path from 'node:path';
-import { isPathTraversal, resolveSafePath } from '../path-scope.js';
 import { postFeedEvent } from './team-db-feed.js';
-import { DEFAULT_TTL_MS, cleanExpiredLeases, promoteNextWaiter, enqueueWaiter } from './team-db-lock-promotion.js';
+import { DEFAULT_TTL_MS, cleanExpiredLeases, promoteNextWaiter, enqueueWaiter, describeLease } from './team-db-lock-promotion.js';
 import { withImmediateTransaction } from './team-db-transaction.js';
+import { resolveLeaseScope, toLeaseKey } from './lease-key.js';
+import { findLapse, explainNotHolder } from './lease-lapse.js';
+import { notifyHolderOfWaiter } from './lease-waiter-notice.js';
+import { lockRoots } from './lease-roots.js';
+import { openTeamDbReadOnly, closeQuietly, safeGet } from './team-db-readonly.js';
 
-export { cleanExpiredLeases, promoteNextWaiter } from './team-db-lock-promotion.js';
+export { cleanExpiredLeases, promoteNextWaiter, describeLease } from './team-db-lock-promotion.js';
 
-const resolveBaseDir = (db, options = {}) => {
-  if (options.cwd) return options.cwd;
+// Leases are keyed from the project root; a relative input resolves from options.cwd.
+const leaseKeyFor = (db, filePath, options) => toLeaseKey(filePath, resolveLeaseScope(db, options));
+
+const leaseInOtherDb = (lockRoot, absPath, cleanId, now) => {
+  const key = path.relative(lockRoot, absPath);
+  const isInside = key !== '' && !key.startsWith('..') && !path.isAbsolute(key);
+  const db = isInside ? openTeamDbReadOnly(lockRoot) : null;
+  const hasDb = Boolean(db);
+  if (!hasDb) return null;
   try {
-    if (typeof db?.location === 'function') {
-      const loc = db.location();
-      if (loc && loc !== ':memory:' && loc.includes('.chemx')) {
-        return path.dirname(path.dirname(path.resolve(loc)));
-      }
-    }
-  } catch {
-    // fallback
+    const lease = describeLease(safeGet(db, 'SELECT * FROM file_leases WHERE file_path = ?', [key]), now);
+    const isForeign = Boolean(lease?.active) && lease.locked_by !== cleanId;
+    return isForeign ? { ...lease, lockRoot } : null;
+  } finally {
+    closeQuietly(db);
   }
-  return process.cwd();
 };
 
+/**
+ * A live lease another handle holds on the same file in another team db (#2581). Until
+ * `chemx team migrate` merges a package db, it and the coordination db both serve leases, keyed
+ * from different roots; a lock taken from the root and one taken from the package must still
+ * collide. Read-only and outside this db's transaction, so two requests racing through different
+ * dbs in the same instant can both pass; the edit guard (edit-locks.js) still reads both dbs.
+ */
+export const findLeaseInOtherDb = (db, cleanPath, cleanId, options = {}) => {
+  const scope = resolveLeaseScope(db, options);
+  const absPath = path.resolve(scope.projectRoot, cleanPath);
+  const now = options.now ?? Date.now();
+  const others = lockRoots(scope.projectRoot, absPath).filter((lockRoot) => lockRoot !== scope.projectRoot);
+  for (const lockRoot of others) {
+    const lease = leaseInOtherDb(lockRoot, absPath, cleanId, now);
+    if (lease) return lease;
+  }
+  return null;
+};
+
+const refuseForOtherDb = (lease, cleanPath) => ({
+  granted: false,
+  reason: 'held_in_other_db',
+  heldBy: lease.locked_by,
+  lease: { file_path: lease.file_path, locked_by: lease.locked_by, expires_at: Number(lease.expires_at), purpose: lease.purpose || '' },
+  dbPath: path.join(lease.lockRoot, '.chemx', 'index.db'),
+  message: `${cleanPath} is leased by ${lease.locked_by} in ${path.join(lease.lockRoot, '.chemx', 'index.db')} (an unmerged package db or the coordination db); not queued here. Wait with chemx wait --lock-free=<file>.`
+});
+
 const normalizeAgentId = (id) => {
   const hasId = Boolean(id);
   if (!hasId) return null;
@@ -33,6 +69,38 @@ const normalizeAgentId = (id) => {
   return isPrefixed ? id : `@${id}`;
 };
 
+// A path that does not exist leases nothing real (#4544). Suggest the same relative path under the
+// coordination root or the repo root when it exists there; `allowNew` skips the check.
+// Returns null when the path exists; otherwise where it was looked for and, when the same path
+// exists under the coordination root, repo root or project root env, a suggestion relative to the
+// caller's cwd (absolute when outside it).
+export const adviseMissingPath = (db, filePath, options = {}) => {
+  const scope = resolveLeaseScope(db, options);
+  const absPath = path.resolve(scope.from, filePath);
+  const isPresent = fs.existsSync(absPath);
+  if (isPresent) return null;
+  const bases = [scope.projectRoot, process.env.CHEMX_PROJECT_ROOT, options.repoRoot].filter(Boolean);
+  const rel = path.isAbsolute(filePath) ? path.relative(scope.projectRoot, absPath) : filePath;
+  const hit = bases.map((base) => path.resolve(base, rel)).find((candidate) => fs.existsSync(candidate));
+  const fromCwd = hit ? path.relative(scope.from, hit) : '';
+  const isInside = fromCwd !== '' && !fromCwd.startsWith('..') && !path.isAbsolute(fromCwd);
+  const nearest = isInside ? fromCwd : hit;
+  const suggestion = hit ? nearest : null;
+  return { absPath, suggestion, from: scope.from };
+};
+
+const missingPathRefusal = (db, filePath, options) => {
+  const advice = adviseMissingPath(db, filePath, options);
+  if (!advice) return null;
+  const hint = advice.suggestion ? ` Did you mean ${advice.suggestion}? (relative to ${advice.from})` : '';
+  return {
+    granted: false,
+    reason: 'path_not_found',
+    suggestion: advice.suggestion,
+    message: `${filePath} does not exist (looked for ${advice.absPath}); no lease was taken.${hint} Pass --new to lease a file you are about to create.`
+  };
+};
+
 export const requestFileLock = (db, filePath, agentId, options = {}) => {
   const hasDb = Boolean(db);
   const hasPath = Boolean(filePath);
@@ -40,14 +108,17 @@ export const requestFileLock = (db, filePath, agentId, options = {}) => {
   const canRequest = hasDb && hasPath && hasAgent;
   if (!canRequest) return { granted: false, reason: 'missing_args' };
 
-  const baseDir = resolveBaseDir(db, options);
-  if (isPathTraversal(filePath, baseDir)) {
-    return { granted: false, reason: 'path_traversal' };
-  }
-  const cleanPath = path.relative(baseDir, resolveSafePath(filePath, baseDir));
+  const cleanPath = leaseKeyFor(db, filePath, options);
+  if (!cleanPath) return { granted: false, reason: 'path_traversal' };
+
+  const mustExist = options.requireExisting === true;
+  const missing = mustExist ? missingPathRefusal(db, filePath, options) : null;
+  if (missing) return missing;
 
   const cleanId = normalizeAgentId(agentId);
   const pid = typeof options.pid === 'number' ? options.pid : 0;
+  const otherDbLease = findLeaseInOtherDb(db, cleanPath, cleanId, options);
+  if (otherDbLease) return refuseForOtherDb(otherDbLease, cleanPath);
 
   return withImmediateTransaction(db, () => {
     cleanExpiredLeases(db);
@@ -60,6 +131,8 @@ export const requestFileLock = (db, filePath, agentId, options = {}) => {
 
     const isAvailable = !existingLease || existingLease.locked_by === cleanId;
     if (isAvailable) {
+      // Read before the grant: a granted lease ends the lapse record's relevance.
+      const lapse = existingLease ? null : findLapse(db, cleanPath, cleanId);
       const upsertSql = `INSERT INTO file_leases (file_path, locked_by, acquired_at, expires_at, purpose, pid)
         VALUES (?, ?, ?, ?, ?, ?)
         ON CONFLICT(file_path) DO UPDATE SET
@@ -75,10 +148,13 @@ export const requestFileLock = (db, filePath, agentId, options = {}) => {
         message: `${cleanId} acquired lock on ${cleanPath}`
       });
 
-      return { granted: true, lease: { file_path: cleanPath, locked_by: cleanId, expires_at: expiresAt, pid } };
+      const lapseNote = lapse ? { previousLapse: lapse } : {};
+      return { granted: true, lease: { file_path: cleanPath, locked_by: cleanId, expires_at: expiresAt, pid }, ...lapseNote };
     }
 
-    return enqueueWaiter(db, cleanPath, cleanId, existingLease, options, now);
+    const queued = enqueueWaiter(db, cleanPath, cleanId, existingLease, options, now);
+    const notice = notifyHolderOfWaiter(db, { queueId: queued.queueId, waiter: cleanId, lease: existingLease, options });
+    return { ...queued, ...notice };
   });
 };
 
@@ -89,11 +165,8 @@ export const releaseFileLock = (db, filePath, agentId, options = {}) => {
   const canRelease = hasDb && hasPath && hasAgent;
   if (!canRelease) return { success: false, reason: 'missing_args' };
 
-  const baseDir = resolveBaseDir(db, options);
-  if (isPathTraversal(filePath, baseDir)) {
-    return { success: false, reason: 'path_traversal' };
-  }
-  const cleanPath = path.relative(baseDir, resolveSafePath(filePath, baseDir));
+  const cleanPath = leaseKeyFor(db, filePath, options);
+  if (!cleanPath) return { success: false, reason: 'path_traversal' };
 
   const cleanId = normalizeAgentId(agentId);
 
@@ -103,7 +176,14 @@ export const releaseFileLock = (db, filePath, agentId, options = {}) => {
     const existingLease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath);
     const isHolder = Boolean(existingLease) && existingLease.locked_by === cleanId;
     if (!isHolder) {
-      return { success: false, reason: 'not_holder' };
+      // A queued non-holder leaves the FIFO queue: release doubles as "cancel my wait".
+      const left = db.prepare("UPDATE file_lock_queue SET status = 'cancelled' WHERE file_path = ? AND agent_id = ? AND status = 'waiting'").run(cleanPath, cleanId);
+      const wasQueued = left.changes > 0;
+      if (wasQueued) return { success: true, dequeued: true, promotedWaiter: null };
+      const lapse = findLapse(db, cleanPath, cleanId);
+      const message = explainNotHolder(cleanPath, lapse, existingLease, Date.now());
+      const lapseNote = lapse ? { lapse } : {};
+      return { success: false, reason: 'not_holder', message, heldBy: existingLease?.locked_by ?? null, ...lapseNote };
     }
 
     db.prepare('DELETE FROM file_leases WHERE file_path = ?').run(cleanPath);
@@ -120,21 +200,73 @@ export const releaseFileLock = (db, filePath, agentId, options = {}) => {
   });
 };
 
+/**
+ * Renew-on-edit and `lock renew`: extends the holder's own live lease to now + one TTL.
+ * One UPDATE scoped to the holder's unexpired row; it never shortens a longer lease and
+ * never touches another agent's lease, the queue or the feed.
+ */
+export const renewHeldLease = (db, leaseKey, agentId, options = {}) => {
+  const now = options.now ?? Date.now();
+  const expiresAt = now + (options.ttlMs || DEFAULT_TTL_MS);
+  const cleanId = normalizeAgentId(agentId);
+  const sql = 'UPDATE file_leases SET expires_at = MAX(expires_at, ?) WHERE file_path = ? AND locked_by = ? AND expires_at > ?';
+  const res = db.prepare(sql).run(expiresAt, leaseKey, cleanId, now);
+  return { renewed: Number(res.changes) > 0, expires_at: expiresAt };
+};
+
+const renewRefusal = (state, cleanId) => {
+  const hasLease = Boolean(state);
+  if (!hasLease) return 'no_lease';
+  const isHolder = state.locked_by === cleanId;
+  if (!isHolder) return 'not_holder';
+  const isLive = Boolean(state.active);
+  if (!isLive) return 'expired';
+  return null;
+};
+
+export const renewFileLock = (db, filePath, agentId, options = {}) => {
+  const hasDb = Boolean(db);
+  const hasPath = Boolean(filePath);
+  const hasAgent = Boolean(agentId);
+  const canRenew = hasDb && hasPath && hasAgent;
+  if (!canRenew) return { renewed: false, reason: 'missing_args' };
+
+  const cleanPath = leaseKeyFor(db, filePath, options);
+  if (!cleanPath) return { renewed: false, reason: 'path_traversal' };
+
+  const cleanId = normalizeAgentId(agentId);
+  const state = describeLease(db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath));
+  const reason = renewRefusal(state, cleanId);
+  const isRefused = Boolean(reason);
+  if (isRefused) return { renewed: false, reason, file_path: cleanPath, lease: state };
+
+  const res = renewHeldLease(db, cleanPath, cleanId, options);
+  const expiresAt = Math.max(Number(state.expires_at), res.expires_at);
+  return { renewed: res.renewed, file_path: cleanPath, locked_by: cleanId, expires_at: expiresAt, purpose: state.purpose || '' };
+};
+
+/** Live leases only (unexpired, holder alive), soonest expiry first. Read-only. */
+export const listActiveLeases = (db, now = Date.now()) => {
+  const hasDb = Boolean(db);
+  if (!hasDb) return [];
+  const rows = db.prepare('SELECT * FROM file_leases ORDER BY expires_at ASC').all();
+  return rows.map((row) => describeLease(row, now)).filter((lease) => lease.active);
+};
+
 export const getFileLockStatus = (db, filePath, options = {}) => {
   const hasDb = Boolean(db);
   const hasPath = Boolean(filePath);
   const canGet = hasDb && hasPath;
   if (!canGet) return null;
 
-  const baseDir = resolveBaseDir(db, options);
-  if (isPathTraversal(filePath, baseDir)) {
-    return { lease: null, waiters: [], error: 'path_traversal' };
-  }
-  const cleanPath = path.relative(baseDir, resolveSafePath(filePath, baseDir));
+  const cleanPath = leaseKeyFor(db, filePath, options);
+  if (!cleanPath) return { lease: null, waiters: [], error: 'path_traversal' };
 
-  cleanExpiredLeases(db);
-  const lease = db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath);
+  // Read-only: an expired or orphaned lease is reported, never deleted, so a status
+  // check cannot race a concurrent acquire. Acquire and release do the cleanup.
+  const state = describeLease(db.prepare('SELECT * FROM file_leases WHERE file_path = ?').get(cleanPath));
+  const isActive = Boolean(state?.active);
   const query = "SELECT * FROM file_lock_queue WHERE file_path = ? AND status = 'waiting' ORDER BY priority ASC, id ASC";
   const waiters = db.prepare(query).all(cleanPath);
-  return { lease: lease || null, waiters };
+  return { lease: isActive ? state : null, expiredLease: isActive ? null : state, waiters };
 };

package/cli/team/team-db-mailbox.js

@@ -1,5 +1,8 @@
 import { toColumnar } from '../columnar.js';
 import { registerAgent } from './team-db-agents.js';
+import { NOT_ARCHIVED_SQL } from './team-db-feed.js';
+import { describeLease } from './team-db-lock-promotion.js';
+import { resolveAgentId } from './agent-identity.js';
 
 export const normalizeHandle = (handle) => {
   if (!handle) return null;
@@ -8,7 +11,7 @@ export const normalizeHandle = (handle) => {
 
 export const sendDirectMessage = (db, params = {}) => {
   if (!db) return null;
-  const author = normalizeHandle(params.author_id) || '@agent';
+  const author = resolveAgentId(params.author_id);
   const recipient = normalizeHandle(params.recipient_id);
   if (!recipient) throw new Error('recipient_id is required');
   registerAgent(db, { id: author, role: 'contributor' });
@@ -47,8 +50,9 @@ export const getAgentMailbox = (db, agentId, options = {}) => {
 
   const limit = Math.min(Number(options.limit || 50), 200);
   const msgParams = [cleanId];
-  let msgSql = 'SELECT id, timestamp, author_id, thread_id, task_id, read_at, message FROM agent_feed WHERE recipient_id = ?';
-  if (options.since) {
+  let msgSql = `SELECT id, timestamp, author_id, thread_id, task_id, read_at, message FROM agent_feed WHERE recipient_id = ? AND ${NOT_ARCHIVED_SQL}`;
+  const hasSince = Boolean(options.since);
+  if (hasSince) {
     msgSql += ' AND id > ?';
     msgParams.push(Number(options.since));
   }
@@ -56,23 +60,26 @@ export const getAgentMailbox = (db, agentId, options = {}) => {
   msgParams.push(limit);
   const messages = db.prepare(msgSql).all(...msgParams);
 
+  // Expired leases and leases whose holder process is dead are not held any more; listing them
+  // would tell the agent it still owns files it lost.
   const leases = db.prepare(`
-    SELECT file_path, locked_by, expires_at, purpose
+    SELECT file_path, locked_by, expires_at, purpose, pid
     FROM file_leases
     WHERE locked_by = ?
     ORDER BY expires_at ASC
-  `).all(cleanId);
+  `).all(cleanId).map((lease) => describeLease(lease)).filter((lease) => lease.active);
 
   const unreadRow = db.prepare(`
     SELECT COUNT(*) as count FROM agent_feed
-    WHERE recipient_id = ? AND read_at IS NULL
+    WHERE recipient_id = ? AND read_at IS NULL AND ${NOT_ARCHIVED_SQL}
   `).get(cleanId);
   const unreadCount = Number(unreadRow?.count || 0);
 
-  if (options.markRead) {
+  const shouldMarkRead = Boolean(options.markRead);
+  if (shouldMarkRead) {
     db.prepare(`
       UPDATE agent_feed SET read_at = ?
-      WHERE recipient_id = ? AND read_at IS NULL
+      WHERE recipient_id = ? AND read_at IS NULL AND ${NOT_ARCHIVED_SQL}
     `).run(Date.now(), cleanId);
   }