@chemx/starter-kit 26.10.7-1061 → 26.10.10-75

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

@@ -0,0 +1,76 @@
+/**
+ * Chemical X Protocol: read-only access to a project's team tables.
+ * Briefs and profiles open .chemx/index.db read-only (the edit-locks.js readLeases pattern), so a
+ * read never creates, migrates or cleans a database. Missing tables or columns read as empty.
+ * Both openers refuse what coordination-root.js refuses (#2581): a db at the temp dir or the
+ * filesystem root, and any db outside the temp dir from a spec process. A refused open is null.
+ */
+import '../silence-warnings.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { teamDbRefusal } from './coordination-root.js';
+
+const loadSqlite = async () => {
+  try {
+    return (await import('node:sqlite')).DatabaseSync;
+  } catch (err) {
+    const isDebug = Boolean(process.env.CHEMX_DEBUG);
+    if (isDebug) process.stderr.write(`[team-db-readonly] node:sqlite unavailable: ${err.message}\n`);
+    return null;
+  }
+};
+const DatabaseSync = await loadSqlite();
+
+export const teamDbPath = (root) => path.join(root, '.chemx', 'index.db');
+
+const mayOpen = (root, dbPath) => Boolean(DatabaseSync) && !teamDbRefusal(root) && fs.existsSync(dbPath);
+
+/** @returns {import('node:sqlite').DatabaseSync | null} null when sqlite or the db file is missing, or the open is refused. */
+export const openTeamDbReadOnly = (root) => {
+  const dbPath = teamDbPath(root);
+  const canOpen = mayOpen(root, dbPath);
+  if (!canOpen) return null;
+  try {
+    return new DatabaseSync(dbPath, { readOnly: true });
+  } catch (err) {
+    const isDebug = Boolean(process.env.CHEMX_DEBUG);
+    if (isDebug) process.stderr.write(`[team-db-readonly] open skipped: ${err.message}\n`);
+    return null;
+  }
+};
+
+// Writable open of an EXISTING db only (never creates one); for cheap presence writes from hooks.
+export const openExistingTeamDb = (root) => {
+  const dbPath = teamDbPath(root);
+  const canOpen = mayOpen(root, dbPath);
+  if (!canOpen) return null;
+  try {
+    const db = new DatabaseSync(dbPath);
+    db.exec('PRAGMA busy_timeout = 500');
+    return db;
+  } catch (err) {
+    const isDebug = Boolean(process.env.CHEMX_DEBUG);
+    if (isDebug) process.stderr.write(`[team-db-readonly] writable open skipped: ${err.message}\n`);
+    return null;
+  }
+};
+
+export const closeQuietly = (db) => {
+  try {
+    const isOpen = Boolean(db?.isOpen);
+    if (isOpen) db.close();
+  } catch {
+    // chemx-allow: best-effort closing a finished handle cannot lose data
+  }
+};
+
+/** Runs a read query; a missing table or column returns [] instead of throwing. */
+export const safeAll = (db, sql, params = []) => {
+  try {
+    return db.prepare(sql).all(...params);
+  } catch {
+    return [];
+  }
+};
+
+export const safeGet = (db, sql, params = []) => safeAll(db, sql, params)[0] ?? null;

package/cli/team/team-db-task-helpers.js

@@ -1,3 +1,6 @@
+import { parseNeedsInput } from './team-needs.js';
+import { buildHandoffHint } from './team-handoff-hint.js';
+
 export const normalizeAgentId = (id) => {
   if (!id) return null;
   return id.startsWith('@') ? id : `@${id}`;
@@ -17,6 +20,7 @@ export const parseTaskRow = (row) => {
     vds_status: row.vds_status || 'ready',
     task_url: row.task_url || '',
     sprint_tag: row.sprint_tag || '',
+    needs: row.needs ?? null,
     dependencies: parseJson(row.dependencies, []),
     result_payload: parseJson(row.result_payload, {}),
     violation_snapshot: parseJson(row.violation_snapshot, {}),
@@ -24,6 +28,9 @@ export const parseTaskRow = (row) => {
   };
 };
 
+// Terminal states that satisfy a dependency: done, plus tasks closed as duplicate or cancelled (#2575).
+const SATISFIED_DEPENDENCY_STATUSES = ['done', 'duplicate', 'cancelled'];
+
 export const checkDependenciesMet = (db, taskId, getTask) => {
   const task = getTask(db, taskId);
   if (!task) return true;
@@ -31,18 +38,28 @@ export const checkDependenciesMet = (db, taskId, getTask) => {
   if (!hasDeps) return true;
 
   const placeholders = task.dependencies.map(() => '?').join(',');
-  const query = `SELECT COUNT(*) as unfinished FROM agent_tasks WHERE id IN (${placeholders}) AND status != 'done'`;
+  const query = `SELECT COUNT(*) as unfinished FROM agent_tasks WHERE id IN (${placeholders}) AND status NOT IN (${SATISFIED_DEPENDENCY_STATUSES.map((s) => `'${s}'`).join(',')})`;
   const res = db.prepare(query).get(...task.dependencies);
   return Number(res?.unfinished || 0) === 0;
 };
 
-export const evaluateClaim = (task, cleanId, isDepsMet) => {
+// Records why unmet dependencies were bypassed, on the task's result_payload (#2589).
+export const recordDepsOverride = (db, task, cleanId, reason) => {
+  const payload = { ...(task.result_payload || {}), deps_override: { by: cleanId, reason, unmet: task.dependencies, at: Date.now() } };
+  db.prepare('UPDATE agent_tasks SET result_payload = ? WHERE id = ?').run(JSON.stringify(payload), Number(task.id));
+};
+
+// ignoreDepsReason: a non-empty string bypasses the dependency check only; a claim held by another handle is still refused.
+export const evaluateClaim = (task, cleanId, isDepsMet, ignoreDepsReason = '') => {
   if (!task) return { allowed: false, reason: 'task_not_found' };
   const isClaimedByOther = task.status === 'in_progress' && Boolean(task.assigned_agent_id) && task.assigned_agent_id !== cleanId;
   if (isClaimedByOther) {
-    return { allowed: false, reason: 'already_claimed', claimedBy: task.assigned_agent_id };
+    const message = `Task #${task.id} is already claimed by ${task.assigned_agent_id}; ${buildHandoffHint(task.id, task.assigned_agent_id, cleanId)}`;
+    return { allowed: false, reason: 'already_claimed', claimedBy: task.assigned_agent_id, message };
   }
-  if (!isDepsMet) {
+  const isOverridden = typeof ignoreDepsReason === 'string' && ignoreDepsReason.trim() !== '';
+  const isBlockedByDeps = !isDepsMet && !isOverridden;
+  if (isBlockedByDeps) {
     return { allowed: false, reason: 'dependencies_unmet', dependencies: task.dependencies };
   }
   return { allowed: true };
@@ -58,12 +75,17 @@ export const executeTaskClaim = (db, taskId, cleanId) => {
 
 export const executeStatusUpdate = (db, taskId, status, options, task) => {
   const now = Date.now();
-  const payloadStr = JSON.stringify(options.resultPayload || task.result_payload || {});
+  // A replacing resultPayload must not drop the deps_override record (#2589).
+  const keptOverride = task.result_payload?.deps_override;
+  const basePayload = options.resultPayload || task.result_payload || {};
+  const mergedPayload = keptOverride && !basePayload.deps_override ? { ...basePayload, deps_override: keptOverride } : basePayload;
+  const payloadStr = JSON.stringify(mergedPayload);
   const receiptObj = options.diffReceipt || options.resultPayload?.receipt || task.diff_receipt || {};
   db.prepare('UPDATE agent_tasks SET status = ?, blocked_reason = ?, result_payload = ?, diff_receipt = ?, updated_at = ? WHERE id = ?')
     .run(status, options.blockedReason || '', payloadStr, JSON.stringify(receiptObj), now, Number(taskId));
 
-  if (['done', 'failed', 'queued'].includes(status) && task.assigned_agent_id) {
+  const shouldReleaseAgent = Boolean(['done', 'failed', 'queued'].includes(status) && task.assigned_agent_id);
+  if (shouldReleaseAgent) {
     db.prepare('UPDATE agents SET current_task_id = NULL, status = ? WHERE id = ?')
       .run('idle', task.assigned_agent_id);
   }
@@ -73,15 +95,18 @@ export const buildTaskListQuery = (filter = {}) => {
   let query = 'SELECT * FROM agent_tasks';
   const conditions = [];
   const params = [];
-  if (filter.status) {
+  const hasStatusFilter = Boolean(filter.status);
+  if (hasStatusFilter) {
     conditions.push('status = ?');
     params.push(filter.status);
   }
-  if (filter.assigned_agent_id) {
+  const hasAgentFilter = Boolean(filter.assigned_agent_id);
+  if (hasAgentFilter) {
     conditions.push('assigned_agent_id = ?');
     params.push(normalizeAgentId(filter.assigned_agent_id));
   }
-  if (filter.target_path) {
+  const hasTargetPathFilter = Boolean(filter.target_path);
+  if (hasTargetPathFilter) {
     conditions.push('target_path = ?');
     params.push(filter.target_path);
   }
@@ -106,25 +131,48 @@ export const buildTaskListQuery = (filter = {}) => {
     conditions.push('priority = ?');
     params.push(Number(filter.priority));
   }
-  if (filter.moscow) {
+  const hasMoscowFilter = Boolean(filter.moscow);
+  if (hasMoscowFilter) {
     conditions.push('moscow = ?');
     params.push(filter.moscow);
   }
-  if (filter.vds_priority) {
+  const hasVdsPriorityFilter = Boolean(filter.vds_priority);
+  if (hasVdsPriorityFilter) {
     conditions.push('vds_priority = ?');
     params.push(filter.vds_priority);
   }
-  if (filter.sprint_tag) {
+  const needsFilter = parseNeedsInput(filter.needs);
+  const hasNeedsFilter = needsFilter !== null;
+  if (hasNeedsFilter) {
+    conditions.push('needs = ?');
+    params.push(needsFilter);
+  }
+  // repo: one owning package ('.' = the coordination root); absent means every repo.
+  const hasRepoFilter = typeof filter.repo === 'string' && filter.repo !== '';
+  if (hasRepoFilter) {
+    conditions.push('repo = ?');
+    params.push(filter.repo);
+  }
+  const hasSprintTagFilter = Boolean(filter.sprint_tag);
+  if (hasSprintTagFilter) {
     conditions.push('sprint_tag = ?');
     params.push(filter.sprint_tag);
   }
-  if (conditions.length > 0) query += ` WHERE ${conditions.join(' AND ')}`;
+  const hasConditions = conditions.length > 0;
+  if (hasConditions) query += ` WHERE ${conditions.join(' AND ')}`;
   query += ' ORDER BY priority ASC, id ASC';
   return { query, params };
 };
 
-export const queryUnassignedHazards = (db) => {
+// options.schema names where agent_tasks lives on this connection ('main', or an ATTACHed team db);
+// options.repo limits the open-task match to one repo; options.insideOnly skips ../ and absolute paths.
+export const queryUnassignedHazards = (db, options = {}) => {
   if (!db) return [];
+  const tasks = `${options.schema || 'main'}.agent_tasks`;
+  const hasRepo = typeof options.repo === 'string';
+  const repoClause = hasRepo ? 'AND t.repo = ?' : '';
+  const vInside = options.insideOnly ? "AND v.file_path NOT LIKE '../%' AND substr(v.file_path, 1, 1) != '/'" : '';
+  const fInside = options.insideOnly ? "AND f.path NOT LIKE '../%' AND substr(f.path, 1, 1) != '/'" : '';
   const query = `
     SELECT 
       COALESCE(v.file_path, f.path) as path,
@@ -136,8 +184,8 @@ export const queryUnassignedHazards = (db) => {
       GROUP_CONCAT(DISTINCT v.rule) as rules_summary
     FROM violations v
     LEFT JOIN files f ON f.path = v.file_path
-    LEFT JOIN agent_tasks t ON t.target_path = v.file_path AND t.status IN ('queued', 'in_progress', 'review')
-    WHERE t.id IS NULL
+    LEFT JOIN ${tasks} t ON t.target_path = v.file_path AND t.status IN ('queued', 'in_progress', 'review') ${repoClause}
+    WHERE t.id IS NULL ${vInside}
     GROUP BY v.file_path
     UNION
     SELECT
@@ -149,15 +197,16 @@ export const queryUnassignedHazards = (db) => {
       f.hazard_count as violation_count,
       'ARCHITECTURAL_HAZARD' as rules_summary
     FROM files f
-    LEFT JOIN agent_tasks t ON t.target_path = f.path AND t.status IN ('queued', 'in_progress', 'review')
+    LEFT JOIN ${tasks} t ON t.target_path = f.path AND t.status IN ('queued', 'in_progress', 'review') ${repoClause}
     WHERE (f.health_score < 90 OR f.hazard_count > 0)
-      AND t.id IS NULL
+      AND t.id IS NULL ${fInside}
       AND f.path NOT IN (SELECT file_path FROM violations)
     GROUP BY f.path
     ORDER BY health_score ASC, hazard_count DESC
   `;
+  const params = hasRepo ? [options.repo, options.repo] : [];
   try {
-    return db.prepare(query).all();
+    return db.prepare(query).all(...params);
   } catch {
     return [];
   }

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

@@ -5,10 +5,11 @@
 
 import {
   normalizeAgentId, parseTaskRow, checkDependenciesMet,
-  evaluateClaim, executeStatusUpdate, buildTaskListQuery
+  evaluateClaim, executeStatusUpdate, buildTaskListQuery, recordDepsOverride
 } from './team-db-task-helpers.js';
 import { withImmediateTransaction } from './team-db-transaction.js';
 import { generateTaskPermalink } from './team-vds.js';
+import { parseNeedsInput } from './team-needs.js';
 
 export const getTask = (db, taskId) => {
   const canGet = Boolean(db) && Boolean(taskId);
@@ -23,12 +24,13 @@ export const createTask = (db, taskData) => {
   const canCreate = Boolean(db) && Boolean(taskData?.title);
   if (!canCreate) return null;
 
+  const needs = parseNeedsInput(taskData.needs);
   const now = Date.now();
   const sql = `INSERT INTO agent_tasks (
     title, description, tier, target_path, target_symbol, status, priority, assigned_agent_id,
     blocked_reason, parent_id, dependencies, created_at, updated_at, result_payload, origin_type,
-    rule_id, violation_snapshot, diff_receipt, moscow, vds_priority, vds_phase, vds_status, task_url, sprint_tag
-  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+    rule_id, violation_snapshot, diff_receipt, moscow, vds_priority, vds_phase, vds_status, task_url, sprint_tag, needs, repo, extra_files
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
   const info = db.prepare(sql).run(
     taskData.title, taskData.description || '', taskData.tier || '',
     taskData.target_path || null, taskData.target_symbol || '', taskData.status || 'queued',
@@ -41,16 +43,19 @@ export const createTask = (db, taskData) => {
     JSON.stringify(taskData.diff_receipt || {}),
     taskData.moscow || 'must', taskData.vds_priority || 'medium',
     taskData.vds_phase || 'planning', taskData.vds_status || 'ready',
-    taskData.task_url || '', taskData.sprint_tag || ''
+    taskData.task_url || '', taskData.sprint_tag || '', needs, taskData.repo || '.',
+    JSON.stringify(Array.isArray(taskData.extra_files) ? taskData.extra_files : [])
   );
   const createdId = info.lastInsertRowid;
-  if (!taskData.task_url) {
+  const isTaskUrlMissing = !taskData.task_url;
+  if (isTaskUrlMissing) {
     db.prepare('UPDATE agent_tasks SET task_url = ? WHERE id = ?').run(generateTaskPermalink(createdId), createdId);
   }
   return getTask(db, createdId);
 };
 
-export const claimTask = (db, taskId, agentId) => {
+// options.ignoreDeps: a reason string; claims despite unmet dependencies and records the reason on the task.
+export const claimTask = (db, taskId, agentId, options = {}) => {
   const canClaim = Boolean(db) && Boolean(taskId) && Boolean(agentId);
   if (!canClaim) return { success: false, reason: 'missing_args' };
 
@@ -58,8 +63,9 @@ export const claimTask = (db, taskId, agentId) => {
   return withImmediateTransaction(db, () => {
     const task = getTask(db, taskId);
     const depsMet = areTaskDependenciesMet(db, taskId);
-    const claimCheck = evaluateClaim(task, cleanId, depsMet);
-    if (!claimCheck.allowed) {
+    const claimCheck = evaluateClaim(task, cleanId, depsMet, options.ignoreDeps);
+    const isClaimDenied = !claimCheck.allowed;
+    if (isClaimDenied) {
       const { allowed, ...failDetails } = claimCheck;
       return { success: false, ...failDetails };
     }
@@ -67,8 +73,11 @@ export const claimTask = (db, taskId, agentId) => {
     const now = Date.now();
     const sql = "UPDATE agent_tasks SET assigned_agent_id = ?, status = 'in_progress', updated_at = ? WHERE id = ? AND status = 'queued' AND (assigned_agent_id IS NULL OR assigned_agent_id = ?);";
     const info = db.prepare(sql).run(cleanId, now, Number(taskId), cleanId);
-    if (info.changes !== 1) return { success: false, reason: 'already_claimed' };
+    const isAlreadyClaimed = info.changes !== 1;
+    if (isAlreadyClaimed) return { success: false, reason: 'already_claimed' };
     db.prepare("UPDATE agents SET current_task_id = ?, status = 'busy' WHERE id = ?").run(Number(taskId), cleanId);
+    const wasOverridden = !depsMet;
+    if (wasOverridden) recordDepsOverride(db, task, cleanId, String(options.ignoreDeps).trim());
     return { success: true, task: getTask(db, taskId) };
   });
 };
@@ -80,6 +89,9 @@ export const updateTaskStatus = (db, taskId, status, options = {}) => {
   return withImmediateTransaction(db, () => {
     const task = getTask(db, taskId);
     if (!task) return null;
+    // options.guard re-checks preconditions on the locked row; a returned value aborts the write.
+    const veto = typeof options.guard === 'function' ? options.guard(task) : null;
+    if (veto) return veto;
     executeStatusUpdate(db, taskId, status, options, task);
     return getTask(db, taskId);
   });

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

@@ -10,6 +10,24 @@ export const isPidAlive = (pid) => {
   }
 };
 
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+const BUSY_CODES = new Set(['SQLITE_BUSY', 'SQLITE_LOCKED']);
+
+// node:sqlite reports contention as { code: 'ERR_SQLITE_ERROR', errcode: 5, message: 'database is locked' };
+// errcode may be an extended code (517 BUSY_SNAPSHOT, 261 BUSY_RECOVERY), so compare the primary byte.
+export const isSqliteBusyError = (err) => {
+  const hasError = Boolean(err);
+  if (!hasError) return false;
+  const primaryCode = typeof err.errcode === 'number' ? err.errcode & 0xff : null;
+  const isBusyCode = primaryCode === SQLITE_BUSY || primaryCode === SQLITE_LOCKED || BUSY_CODES.has(err.code);
+  return isBusyCode || /database is locked|database is busy|SQLITE_BUSY/i.test(String(err.message || ''));
+};
+
+const sleepSync = (ms) => {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+
 export const withImmediateTransaction = (db, callback, maxRetries = 5) => {
   const hasDb = Boolean(db);
   const isFunction = typeof callback === 'function';
@@ -36,14 +54,11 @@ export const withImmediateTransaction = (db, callback, maxRetries = 5) => {
           process.stderr.write(`[SWARM] Transaction rollback failed: ${rollbackNotice}\n`);
         }
       }
-      const isSqliteBusy = err && (err.code === 'SQLITE_BUSY' || String(err.message).includes('busy'));
       const hasRetriesLeft = attempts < maxRetries;
-      const canRetry = isSqliteBusy && hasRetriesLeft;
+      const canRetry = isSqliteBusyError(err) && hasRetriesLeft;
 
       if (canRetry) {
-        const sleepMs = Math.floor(10 + Math.random() * 20);
-        const start = Date.now();
-        while (Date.now() - start < sleepMs) {}
+        sleepSync(Math.floor(10 * attempts + Math.random() * 20 * attempts));
         continue;
       }
       throw err;

package/cli/team/team-db.js

@@ -32,12 +32,14 @@ export {
   promoteNextWaiter
 } from './team-db-locks.js';
 
-import { cleanExpiredLeases } from './team-db-locks.js';
+import { describeLease } from './team-db-locks.js';
 import { queryFeed } from './team-db-feed.js';
 
+const RECENT_FEED_LIMIT = 4;
+
+// Read-only: dashboards and SSE refreshes never delete leases (see cleanExpiredLeases for the write path).
 export const getSwarmStatus = (db) => {
   if (!db) return null;
-  cleanExpiredLeases(db);
 
   const agents = db.prepare('SELECT status, COUNT(*) as count FROM agents GROUP BY status').all();
   const agentSummary = { total: 0, idle: 0, busy: 0, offline: 0 };
@@ -53,7 +55,9 @@ export const getSwarmStatus = (db) => {
     taskSummary.total += t.count;
   }
 
-  const activeLocks = db.prepare('SELECT file_path, locked_by, expires_at FROM file_leases').all();
+  const leaseStates = db.prepare('SELECT file_path, locked_by, expires_at, pid FROM file_leases').all().map((lease) => describeLease(lease));
+  const activeLocks = leaseStates.filter((lease) => lease.active).map(({ file_path, locked_by, expires_at }) => ({ file_path, locked_by, expires_at }));
+  const expiredLocks = leaseStates.length - activeLocks.length;
   const waitingLocks = db.prepare("SELECT COUNT(*) as count FROM file_lock_queue WHERE status = 'waiting'").get();
 
   const blockedTasks = db.prepare(`
@@ -75,13 +79,16 @@ export const getSwarmStatus = (db) => {
     cost_usd: Number(Number(tokenRow.cost).toFixed(6))
   };
 
-  const recentFeed = queryFeed(db, { limit: 5 });
+  // Latest mode: the newest rows in chronological order. Four matches what the status card prints
+  // (formatSwarmStatusCard takes slice(0, 4)), so the card never drops the newest event.
+  const recentFeed = queryFeed(db, { limit: RECENT_FEED_LIMIT });
 
   return {
     agents: agentSummary,
     tasks: taskSummary,
     locks: {
       active: activeLocks.length,
+      expired: expiredLocks,
       waiting: waitingLocks?.count || 0,
       leases: activeLocks
     },