archgraph-argo 0.20.4 → 0.20.5

package/argo/scripts/ensureArgoHarnessEnvironment.js

@@ -38,7 +38,13 @@ const REQUIRED_TOOL_NAMES = [
 // `includeBootstrap` is true for the standalone CLI (it calls initializeWorkspace
 // to bootstrap the workspace); the initializeWorkspace MCP tool passes false
 // because it already bootstrapped — avoids re-entrancy through ensureWorkspaceBootstrap.
-async function buildHarnessReport({ checkOnly = false, workspaceRoot, includeBootstrap = true }) {
+async function buildHarnessReport(options = {}) {
+  const { checkOnly = false, workspaceRoot, includeBootstrap = true } = options;
+  const { withAlignmentLock } = require('./graph-rag/semanticAlignmentLock.js');
+  return withAlignmentLock(workspaceRoot, () => runHarnessReport({ checkOnly, workspaceRoot, includeBootstrap }));
+}
+
+async function runHarnessReport({ checkOnly, workspaceRoot, includeBootstrap }) {
   const reportPath = path.join(workspaceRoot, '.argo', 'temp', 'argo-harness-init-report.json');
   const report = {
     status: 'ok',

package/argo/scripts/graph-rag/semanticAlignmentLock.js

@@ -0,0 +1,76 @@
+'use strict';
+
+// Cross-process, single-flight lock for the heavy semantic-index alignment
+// (workspace bootstrap + semantic backfill + Neo4j sync + EA projection). Any
+// invocation that can rebuild the index -- the MCP startup preheat, the
+// query-path auto-alignment, and an explicit `argo init` (initializeWorkspace),
+// in this process or another -- acquires this lock, so they serialize instead of
+// racing (duplicate embeddings, concurrent Neo4j upserts, concurrent .qea
+// rebuild, readiness/report races).
+//
+// The lock is a regular file created with `wx` under <workspace>/.argo/temp. A
+// holder that crashes leaves a stale file; a lock older than `staleMs` is stolen.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCK_RELATIVE_PATH = path.join('.argo', 'temp', 'semantic-alignment.lock');
+const DEFAULT_WAIT_MS = 10 * 60 * 1000;
+const DEFAULT_STALE_MS = 15 * 60 * 1000;
+
+function alignmentLockPath(repositoryRoot) {
+  return path.join(repositoryRoot, ...LOCK_RELATIVE_PATH.split(path.sep));
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function withAlignmentLock(repositoryRoot, action, options = {}) {
+  const waitMs = Number.isFinite(options.waitMs) && options.waitMs > 0 ? options.waitMs : DEFAULT_WAIT_MS;
+  const staleMs = Number.isFinite(options.staleMs) && options.staleMs > 0 ? options.staleMs : DEFAULT_STALE_MS;
+  const file = alignmentLockPath(repositoryRoot);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const deadline = Date.now() + waitMs;
+  let fd = null;
+  for (;;) {
+    try {
+      fd = fs.openSync(file, 'wx');
+      break;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') {
+        throw error;
+      }
+      let stale = false;
+      try {
+        stale = (Date.now() - fs.statSync(file).mtimeMs) > staleMs;
+      } catch {
+        stale = true;
+      }
+      if (stale) {
+        try { fs.unlinkSync(file); } catch { /* raced with another stealer */ }
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        const timeout = new Error('SEMANTIC_ALIGNMENT_LOCK_TIMEOUT');
+        timeout.category = 'SEMANTIC_ALIGNMENT_LOCK_TIMEOUT';
+        timeout.message = 'Another semantic alignment is already running and did not finish in time.';
+        timeout.action = 'Wait for the running alignment (argo init) to finish, then retry.';
+        throw timeout;
+      }
+      await sleep(250);
+    }
+  }
+  try {
+    try { fs.writeSync(fd, String(process.pid)); } catch { /* best-effort owner marker */ }
+    return await action();
+  } finally {
+    try { fs.closeSync(fd); } catch { /* ignore */ }
+    try { fs.unlinkSync(file); } catch { /* already gone */ }
+  }
+}
+
+module.exports = {
+  withAlignmentLock,
+  alignmentLockPath,
+};

package/argo/scripts/graph-rag/semanticAlignmentRunner.js

@@ -34,6 +34,18 @@ function isSemanticReady(repositoryRoot) {
   }
 }
 
+// A project is "initialized" once its canonical graph exists. The startup
+// preheat must NEVER bootstrap a brand-new project: creating files / running a
+// full backfill for an unknown workspace in the background is surprising and
+// would race an explicit `argo init`. New projects initialize explicitly.
+function isProjectInitialized(repositoryRoot) {
+  try {
+    return fs.existsSync(path.join(repositoryRoot, 'design', 'KG', 'SystemArchitecture.json'));
+  } catch {
+    return false;
+  }
+}
+
 function alignmentError() {
   const error = new Error('SEMANTIC_AUTO_ALIGNMENT_FAILED');
   error.category = 'SEMANTIC_AUTO_ALIGNMENT_FAILED';
@@ -79,7 +91,7 @@ function runSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
 // otherwise it starts the rebuild in the background so the first query rarely
 // pays for it. Safe to call repeatedly (guarded + de-duplicated).
 function preheatSemanticAlignment(repositoryRoot = getWorkspaceRoot()) {
-  if (preheated || !repositoryRoot || isSemanticReady(repositoryRoot)) {
+  if (preheated || !repositoryRoot || !isProjectInitialized(repositoryRoot) || isSemanticReady(repositoryRoot)) {
     return;
   }
   preheated = true;
@@ -91,5 +103,6 @@ module.exports = {
   runSemanticAlignment,
   preheatSemanticAlignment,
   isSemanticReady,
+  isProjectInitialized,
   readinessRecordPath,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archgraph-argo",
-  "version": "0.20.4",
+  "version": "0.20.5",
   "description": "Deploy the ArchGraph ARGO toolchain, skills, and rules (schema, scripts, argo-init skill, global rule) with one command.",
   "license": "MIT",
   "bin": {