@inkobytes/nexus 1.0.0

package/src/lib/blackboard.js

@@ -0,0 +1,90 @@
+/**
+ * Blackboard — serialized read/write to _NEXUS.md
+ * All writes go through a lockfile to prevent race conditions
+ * between agents writing simultaneously.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmdirSync } from 'fs';
+import { resolve } from 'path';
+import { getConfig } from './config.js';
+
+function getLockPath(blackboardPath) {
+  return blackboardPath + '.lockdir';
+}
+
+function acquireLock(blackboardPath, maxAttempts = 25, intervalMs = 200) {
+  const lockPath = getLockPath(blackboardPath);
+  let attempts = 0;
+
+  while (attempts < maxAttempts) {
+    try {
+      mkdirSync(lockPath);
+      return true;
+    } catch {
+      attempts++;
+      if (attempts >= maxAttempts) {
+        console.error('[WARN] Blackboard write lock timeout');
+        return false;
+      }
+      const start = Date.now();
+      while (Date.now() - start < intervalMs) { /* spin */ }
+    }
+  }
+  return false;
+}
+
+function releaseLock(blackboardPath) {
+  const lockPath = getLockPath(blackboardPath);
+  try {
+    rmdirSync(lockPath);
+  } catch { /* already gone */ }
+}
+
+export function withLock(fn) {
+  const config = getConfig();
+  const boardPath = resolve(config.root, '_NEXUS.md');
+
+  if (!acquireLock(boardPath)) {
+    throw new Error('Could not acquire blackboard lock');
+  }
+
+  try {
+    return fn(boardPath);
+  } finally {
+    releaseLock(boardPath);
+  }
+}
+
+export function readBoard() {
+  const config = getConfig();
+  const boardPath = resolve(config.root, '_NEXUS.md');
+
+  if (!existsSync(boardPath)) return '';
+  return readFileSync(boardPath, 'utf-8');
+}
+
+export function appendEntry(line) {
+  withLock((boardPath) => {
+    if (!existsSync(boardPath)) writeFileSync(boardPath, '', 'utf-8');
+    const content = readFileSync(boardPath, 'utf-8');
+    writeFileSync(boardPath, content + line + '\n', 'utf-8');
+  });
+}
+
+export function removeEntry(needle) {
+  withLock((boardPath) => {
+    if (!existsSync(boardPath)) return;
+    const content = readFileSync(boardPath, 'utf-8');
+    const filtered = content
+      .split('\n')
+      .filter(line => !line.includes(needle))
+      .join('\n');
+    writeFileSync(boardPath, filtered, 'utf-8');
+  });
+}
+
+export function clearBoard() {
+  withLock((boardPath) => {
+    writeFileSync(boardPath, '', 'utf-8');
+  });
+}

package/src/lib/config.js

@@ -0,0 +1,38 @@
+/**
+ * Config — resolve project root and Nexus paths
+ */
+
+import { existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { cwd } from 'process';
+
+let _config = null;
+
+export function getConfig(fromDir) {
+  if (_config) return _config;
+
+  const root = fromDir || cwd();
+  const lockDir = join(root, '.nexus', 'locks');
+  const budgetFile = join(root, '.nexus', 'agent-budgets.json');
+
+  _config = {
+    root,
+    lockDir,
+    budgetFile,
+    blackboard: join(root, '_NEXUS.md'),
+    standup: join(root, '_NEXUS_STANDUP.md'),
+    report: join(root, '_NEXUS_REPORT.md'),
+    ledger: join(root, '_NEXUS_LEDGER.md'),
+    queue: join(root, '_NEXUS_QUEUE.md'),
+    staleThreshold: 600, // 10 minutes in seconds
+    maxDumpFiles: 20,
+    maxClaimAttempts: 10,
+    claimRetryMs: 2000,
+  };
+
+  return _config;
+}
+
+export function resetConfig() {
+  _config = null;
+}

package/src/lib/dump.js

@@ -0,0 +1,63 @@
+/**
+ * File state dumper — outputs fresh file contents after a claim
+ * to override stale agent context.
+ */
+
+import { existsSync, statSync, readFileSync, readdirSync } from 'fs';
+import { join, resolve } from 'path';
+import { getConfig } from './config.js';
+import { normalizeTarget } from './pathSafety.js';
+
+/**
+ * Recursively collect files in a directory
+ */
+function collectFiles(dir, files = []) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(fullPath, files);
+    } else {
+      files.push(fullPath);
+    }
+  }
+  return files.sort();
+}
+
+/**
+ * Dump file state for a target (file or directory).
+ * Returns the output string.
+ */
+export function dumpState(target) {
+  const config = getConfig();
+  const safeTarget = normalizeTarget(target);
+  const absoluteTarget = resolve(config.root, safeTarget);
+  const lines = [];
+
+  lines.push('--- START OF FRESH FILE STATE ---');
+
+  if (!existsSync(absoluteTarget)) {
+    lines.push('(New file/dir — does not exist yet)');
+  } else if (statSync(absoluteTarget).isDirectory()) {
+    const files = collectFiles(absoluteTarget);
+
+    if (files.length > config.maxDumpFiles) {
+      lines.push(`[WARN] Directory contains ${files.length} files. Showing first ${config.maxDumpFiles}.`);
+      for (const f of files.slice(0, config.maxDumpFiles)) {
+        lines.push(`=== ${f} ===`);
+        lines.push(readFileSync(f, 'utf-8'));
+      }
+      lines.push(`=== ... and ${files.length - config.maxDumpFiles} more files ===`);
+    } else {
+      for (const f of files) {
+        lines.push(`=== ${f} ===`);
+        lines.push(readFileSync(f, 'utf-8'));
+      }
+    }
+  } else {
+    lines.push(readFileSync(absoluteTarget, 'utf-8'));
+  }
+
+  lines.push('--- END OF FRESH FILE STATE ---');
+  return lines.join('\n');
+}

package/src/lib/git.js

@@ -0,0 +1,111 @@
+/**
+ * Git helper — stage + commit with pathspec safety
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { spawnSync } from 'child_process';
+import { getConfig } from './config.js';
+import { normalizeTarget } from './pathSafety.js';
+
+function sleep(ms) {
+  const start = Date.now();
+  while (Date.now() - start < ms) { /* wait */ }
+}
+
+function isIndexLockError(message) {
+  return message.includes('.git/index.lock') || message.includes('index.lock');
+}
+
+function git(args) {
+  const result = spawnSync('git', args, {
+    cwd: getConfig().root,
+    encoding: 'utf-8',
+    stdio: 'pipe',
+  });
+
+  if (result.status !== 0) {
+    const detail = result.stderr?.trim() || result.stdout?.trim() || `git ${args[0]} failed`;
+    throw new Error(detail);
+  }
+
+  return result.stdout || '';
+}
+
+function gitWithIndexLockRetry(args, maxRetries, retryMs) {
+  let attempt = 0;
+  let lastError;
+
+  while (attempt < maxRetries) {
+    try {
+      return git(args);
+    } catch (err) {
+      lastError = err;
+      const indexLockPath = join(getConfig().root, '.git', 'index.lock');
+      const message = err.message || '';
+      if (!isIndexLockError(message) && !existsSync(indexLockPath)) throw err;
+      attempt++;
+      if (attempt < maxRetries) sleep(retryMs);
+    }
+  }
+
+  throw new Error(`Git index stayed locked after ${maxRetries} attempts. Another git process may still be running; retry the release when it finishes. Last error: ${lastError?.message || 'unknown error'}`);
+}
+
+/**
+ * Stage and commit a target (file or directory).
+ * Uses `git add` + `git commit --` pathspec to prevent stowaways.
+ */
+export function stageAndCommit(target, message, maxRetries = 5, retryMs = 1000) {
+  const safeTarget = normalizeTarget(target);
+  let agent = '';
+
+  if (typeof maxRetries === 'string') {
+    agent = maxRetries.trim();
+    maxRetries = 5;
+    retryMs = 1000;
+  } else if (typeof retryMs === 'string') {
+    agent = retryMs.trim();
+    retryMs = 1000;
+  }
+
+  const attribution = agent ? agent : 'Agent';
+
+  // Stage the target
+  try {
+    gitWithIndexLockRetry(['add', '--', safeTarget], maxRetries, retryMs);
+  } catch (err) {
+    return { success: false, message: err.message || 'Git add failed.' };
+  }
+
+  let attempt = 0;
+  while (attempt < maxRetries) {
+    try {
+      gitWithIndexLockRetry(['commit', '-m', `[${attribution}] ${message}`, '--', safeTarget], maxRetries, retryMs);
+      const sha = git(['rev-parse', 'HEAD']).trim();
+      return { success: true, sha };
+    } catch (err) {
+      attempt++;
+      if (attempt >= maxRetries) {
+        // Check if there's actually nothing to commit
+        try {
+          const status = git(['status', '--porcelain', '--', safeTarget]);
+          if (!status.trim()) {
+            return { success: true, message: 'Nothing to commit (clean)' };
+          }
+        } catch { /* fall through */ }
+
+        return {
+          success: false,
+          message: err.message?.includes('Git index stayed locked')
+            ? err.message
+            : `Git commit failed after ${maxRetries} attempts.`,
+        };
+      }
+      // Brief pause before retry
+      sleep(retryMs);
+    }
+  }
+
+  return { success: false, message: 'Git commit failed.' };
+}

package/src/lib/lockManager.js

@@ -0,0 +1,302 @@
+/**
+ * Lock Manager — atomic mkdir-based file/directory locking
+ * with hierarchy enforcement and stale detection.
+ */
+
+import { spawnSync } from 'child_process';
+import { mkdirSync, rmdirSync, existsSync, readFileSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'fs';
+import { join, dirname } from 'path';
+import { getConfig } from './config.js';
+import { lockNameToTarget, normalizeTarget, targetToLockName } from './pathSafety.js';
+
+export function getLockPath(target) {
+  const config = getConfig();
+  return join(config.lockDir, targetToLockName(target));
+}
+
+/**
+ * Check for parent directory locks (upward traversal)
+ */
+function checkParentLocks(target, lockDir) {
+  let parent = dirname(target);
+  while (parent !== '.' && parent !== '/') {
+    const parentLock = join(lockDir, targetToLockName(parent));
+    if (existsSync(parentLock)) {
+      return parent;
+    }
+    parent = dirname(parent);
+  }
+  return null;
+}
+
+/**
+ * Check for child file locks inside a directory (downward check)
+ */
+function checkChildLocks(target, lockDir) {
+  const normalizedTarget = normalizeTarget(target);
+
+  if (!existsSync(lockDir)) return null;
+
+  const locks = readdirSync(lockDir);
+  for (const lock of locks) {
+    const lockPath = join(lockDir, lock);
+    if (!existsSync(lockPath)) continue;
+    try { if (!statSync(lockPath).isDirectory()) continue; } catch { continue; }
+
+    let lockedTarget = '';
+    try {
+      lockedTarget = lockNameToTarget(lock);
+    } catch {
+      continue;
+    }
+
+    if (lockedTarget.startsWith(`${normalizedTarget}/`) && lockedTarget !== normalizedTarget) {
+      return lockedTarget;
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a lock is stale (older than threshold)
+ */
+function isStale(lockPath) {
+  const config = getConfig();
+  const tsFile = join(lockPath, 'ts');
+
+  if (!existsSync(tsFile)) return false;
+
+  const lockTs = parseInt(readFileSync(tsFile, 'utf-8').trim(), 10);
+  const now = Math.floor(Date.now() / 1000);
+  const age = now - lockTs;
+
+  return age >= config.staleThreshold ? age : false;
+}
+
+/**
+ * Break a stale lock
+ */
+const LOCK_METADATA_FILES = [
+  'ts',
+  'agent',
+  'intent',
+  'subagents',
+  'model',
+  'thinking',
+  'verified',
+  'trust-source',
+  'claim-head',
+];
+
+export function readGitHead(root) {
+  const result = spawnSync('git', ['rev-parse', 'HEAD'], {
+    cwd: root,
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  const head = result.stdout?.trim();
+  return result.status === 0 && head ? head : 'unknown';
+}
+
+function breakLock(lockPath) {
+  for (const f of LOCK_METADATA_FILES) {
+    try { unlinkSync(join(lockPath, f)); } catch { /* ok */ }
+  }
+  try { rmdirSync(lockPath); } catch { /* ok */ }
+}
+
+function detectTrust() {
+  if (process.env.CLAUDECODE === '1') return { verified: true, trustSource: 'harness' };
+  if (process.env.NEXUS_AGENT)        return { verified: true, trustSource: 'operator' };
+  return { verified: false, trustSource: 'unverified' };
+}
+
+/**
+ * Attempt to acquire a lock on a file or directory.
+ * Returns { success, message, staleAge? }
+ */
+export function acquireLock(target, agentName, intent, subagents = 0, metadata = {}) {
+  const config = getConfig();
+  const normalizedTarget = normalizeTarget(target);
+  const lockPath = getLockPath(normalizedTarget);
+
+  // Ensure lock directory exists
+  mkdirSync(config.lockDir, { recursive: true });
+
+  // Hierarchy check: parent locked?
+  const lockedParent = checkParentLocks(normalizedTarget, config.lockDir);
+  if (lockedParent) {
+    return {
+      success: false,
+      message: `Cannot claim '${normalizedTarget}' — parent dir '${lockedParent}' is locked by another agent.`,
+    };
+  }
+
+  // Hierarchy check: child locked? (only for directory claims)
+  try {
+    if (existsSync(normalizedTarget) && statSync(normalizedTarget).isDirectory()) {
+      const lockedChild = checkChildLocks(normalizedTarget, config.lockDir);
+      if (lockedChild) {
+        return {
+          success: false,
+          message: `Cannot claim '${normalizedTarget}' — a file inside it is already locked: ${lockedChild}`,
+        };
+      }
+    }
+  } catch { /* target might not exist yet, that's fine */ }
+
+  // Stale lock detection
+  if (existsSync(lockPath)) {
+    const staleAge = isStale(lockPath);
+    if (staleAge) {
+      console.log(`[WARN] Stale lock detected (${staleAge}s old). Auto-breaking.`);
+      breakLock(lockPath);
+    }
+  }
+
+  // Attempt atomic lock via mkdir
+  let attempts = 0;
+  while (attempts < config.maxClaimAttempts) {
+    try {
+      mkdirSync(lockPath);
+
+      // Write timestamp, agent, intent, and subagents for stale detection and dashboard display
+      writeFileSync(join(lockPath, 'ts'), String(Math.floor(Date.now() / 1000)), 'utf-8');
+      writeFileSync(join(lockPath, 'agent'), agentName || '', 'utf-8');
+      writeFileSync(join(lockPath, 'intent'), intent || '', 'utf-8');
+      if (subagents > 0) writeFileSync(join(lockPath, 'subagents'), String(subagents), 'utf-8');
+      if (metadata.model) writeFileSync(join(lockPath, 'model'), metadata.model, 'utf-8');
+      if (metadata.thinking) writeFileSync(join(lockPath, 'thinking'), metadata.thinking, 'utf-8');
+      const { verified, trustSource } = detectTrust();
+      writeFileSync(join(lockPath, 'verified'), verified ? 'true' : 'false', 'utf-8');
+      writeFileSync(join(lockPath, 'trust-source'), trustSource, 'utf-8');
+      writeFileSync(join(lockPath, 'claim-head'), readGitHead(config.root), 'utf-8');
+
+      return {
+        success: true,
+        message: `[LOCK ACQUIRED] - ${agentName} is clear to modify ${normalizedTarget}`,
+      };
+    } catch {
+      attempts++;
+      if (attempts >= config.maxClaimAttempts) {
+        return {
+          success: false,
+          message: `File locked by another agent. Failed after ${attempts * config.claimRetryMs / 1000}s.`,
+        };
+      }
+      const start = Date.now();
+      while (Date.now() - start < config.claimRetryMs) { /* spin wait */ }
+    }
+  }
+
+  return { success: false, message: 'Lock acquisition failed.' };
+}
+
+/**
+ * Release a lock. Returns { success, message }
+ */
+export function releaseLock(target) {
+  const normalizedTarget = normalizeTarget(target);
+  const lockPath = getLockPath(normalizedTarget);
+
+  if (!existsSync(lockPath)) {
+    return { success: false, message: `No lock found for: ${normalizedTarget}` };
+  }
+
+  for (const f of LOCK_METADATA_FILES) {
+    try { unlinkSync(join(lockPath, f)); } catch { /* ok */ }
+  }
+  try {
+    rmdirSync(lockPath);
+    return { success: true, message: `Lock released for: ${normalizedTarget}` };
+  } catch (err) {
+    return { success: false, message: `Failed to release lock: ${err.message}` };
+  }
+}
+
+/**
+ * List all current locks with metadata
+ */
+export function listLocks() {
+  const config = getConfig();
+  if (!existsSync(config.lockDir)) return [];
+
+  const locks = [];
+  const entries = readdirSync(config.lockDir);
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.lock')) continue;
+    const lockPath = join(config.lockDir, entry);
+    try {
+      if (!statSync(lockPath).isDirectory()) continue;
+    } catch { continue; }
+
+    let target;
+    try { target = lockNameToTarget(entry); } catch { continue; }
+    const tsFile = join(lockPath, 'ts');
+    let age = null;
+
+    if (existsSync(tsFile)) {
+      const lockTs = parseInt(readFileSync(tsFile, 'utf-8').trim(), 10);
+      age = Math.floor(Date.now() / 1000) - lockTs;
+    }
+
+    const readMeta = (name) => {
+      try { return readFileSync(join(lockPath, name), 'utf-8').trim(); } catch { return ''; }
+    };
+
+    const subagentsRaw = readMeta('subagents');
+    locks.push({
+      target,
+      age,
+      lockPath,
+      agent: readMeta('agent'),
+      intent: readMeta('intent'),
+      subagents: subagentsRaw ? parseInt(subagentsRaw, 10) : 0,
+      model: readMeta('model'),
+      thinking: readMeta('thinking'),
+      verified: readMeta('verified') === 'true',
+      trustSource: readMeta('trust-source') || 'unverified',
+      claimHead: readMeta('claim-head') || 'unknown',
+    });
+  }
+
+  return locks;
+}
+
+/**
+ * Find and break all stale locks. Returns array of broken lock targets.
+ */
+export function breakStaleLocks() {
+  const config = getConfig();
+  const broken = [];
+
+  for (const lock of listLocks()) {
+    if (lock.age !== null && lock.age >= config.staleThreshold) {
+      breakLock(lock.lockPath);
+      broken.push({ target: lock.target, age: lock.age });
+    }
+  }
+
+  return broken;
+}
+
+/**
+ * Nuke all locks
+ */
+export function nukeAllLocks() {
+  const config = getConfig();
+  if (!existsSync(config.lockDir)) return;
+
+  const entries = readdirSync(config.lockDir);
+  for (const entry of entries) {
+    const lockPath = join(config.lockDir, entry);
+    try {
+      if (statSync(lockPath).isDirectory()) {
+        const tsFile = join(lockPath, 'ts');
+        try { unlinkSync(tsFile); } catch { /* ok */ }
+        rmdirSync(lockPath);
+      }
+    } catch { /* ok */ }
+  }
+}

package/src/lib/pathSafety.js

@@ -0,0 +1,41 @@
+import { isAbsolute, relative, resolve, sep } from 'path';
+import { getConfig } from './config.js';
+
+const RESERVED_ROOTS = new Set(['.git', '.nexus']);
+
+export function normalizeTarget(target) {
+  if (typeof target !== 'string' || !target.trim()) {
+    throw new Error('Missing target path.');
+  }
+
+  const raw = target.trim();
+  if (isAbsolute(raw)) {
+    throw new Error('Target must be a relative path inside the repo.');
+  }
+
+  const root = resolve(getConfig().root);
+  const absoluteTarget = resolve(root, raw);
+  const relativeTarget = relative(root, absoluteTarget);
+
+  if (!relativeTarget || relativeTarget.startsWith('..') || isAbsolute(relativeTarget)) {
+    throw new Error('Target must stay inside the repo.');
+  }
+
+  const normalized = relativeTarget.split(sep).join('/');
+  const firstPart = normalized.split('/')[0];
+
+  if (RESERVED_ROOTS.has(firstPart)) {
+    throw new Error(`Target cannot be inside ${firstPart}.`);
+  }
+
+  return normalized;
+}
+
+export function targetToLockName(target) {
+  return `${encodeURIComponent(normalizeTarget(target)).replaceAll('%', '~')}.lock`;
+}
+
+export function lockNameToTarget(lockName) {
+  const base = lockName.replace(/\.lock$/, '').replaceAll('~', '%');
+  return normalizeTarget(decodeURIComponent(base));
+}